diff --git a/collector/generator/main_alloy.tpl b/collector/generator/main_alloy.tpl index caea6e3b312..17d4936e1b9 100644 --- a/collector/generator/main_alloy.tpl +++ b/collector/generator/main_alloy.tpl @@ -16,7 +16,5 @@ func newAlloyCommand(params otelcol.CollectorSettings) *cobra.Command { flowCmd := flowcmd.RootCommand() flowCmd.AddCommand(otelCmd) - // TODO: Officially add this command to expose in a follow up PR - otelCmd.Hidden = true return flowCmd } \ No newline at end of file diff --git a/collector/main_alloy.go b/collector/main_alloy.go index 700fb61085e..244f5eb1f0b 100644 --- a/collector/main_alloy.go +++ b/collector/main_alloy.go @@ -17,7 +17,5 @@ func newAlloyCommand(params otelcol.CollectorSettings) *cobra.Command { flowCmd := flowcmd.RootCommand() flowCmd.AddCommand(otelCmd) - // TODO: Officially add this command to expose in a follow up PR - otelCmd.Hidden = true return flowCmd } \ No newline at end of file diff --git a/docs/sources/reference/cli/_index.md b/docs/sources/reference/cli/_index.md index d4c51254d44..05a6b18b52e 100644 --- a/docs/sources/reference/cli/_index.md +++ b/docs/sources/reference/cli/_index.md @@ -16,7 +16,8 @@ Available commands: * [`convert`][convert]: Convert an {{< param "PRODUCT_NAME" >}} configuration file. * [`fmt`][fmt]: Format an {{< param "PRODUCT_NAME" >}} configuration file. -* [`run`][run]: Start {{< param "PRODUCT_NAME" >}}, given a configuration file. +* [`run`][run]: Start {{< param "PRODUCT_NAME" >}} with the Default Engine, given an Alloy syntax configuration file. +* [`otel`][otel]: Start {{< param "PRODUCT_NAME" >}} with the experimental OTel Engine, given an Open Telemetry Collector YAML configuration file. * [`tools`][tools]: Read the WAL and provide statistical information. * `completion`: Generate shell completion for the `alloy` CLI. * `help`: Print help for supported commands. @@ -24,4 +25,5 @@ Available commands: [run]: ./run/ [fmt]: ./fmt/ [convert]: ./convert/ +[otel]: ./otel/ [tools]: ./tools/ diff --git a/docs/sources/reference/cli/otel.md b/docs/sources/reference/cli/otel.md new file mode 100644 index 00000000000..9e81a239646 --- /dev/null +++ b/docs/sources/reference/cli/otel.md @@ -0,0 +1,130 @@ +--- +canonical: https://grafana.com/docs/alloy/latest/reference/cli/otel/ +description: Learn about the otel command +labels: + stage: experimental + products: + - oss +title: otel +_build: + list: false +noindex: true +weight: 350 +--- + +# `otel` + +The `otel` command runs Grafana Alloy using the OpenTelemetry (OTel) Collector engine. This command accepts OpenTelemetry Collector YAML configuration files. + +The Alloy OTel distribution includes receivers, processors, exporters, extensions, and connectors from the OpenTelemetry Collector core and contrib repositories. This includes components for OTLP, Prometheus, Kafka, Zipkin, and other popular integrations. + +As with the `run` command, this runs in the foreground until an interrupt is received. + +{{< docs/shared lookup="stability/experimental_feature.md" source="alloy" version="" >}} + +## Usage + +```shell +alloy otel --config= [ ...] +``` + +Replace the following: + +* _``_: Path to an OpenTelemetry Collector configuration file. +* _``_: One or more flags that configure the OpenTelemetry Collector. + +## Configuration + +The `otel` command accepts standard OpenTelemetry Collector YAML configuration files. The configuration file defines receivers, processors, exporters, and other components that make up your telemetry pipeline. + +For information about configuration options, refer to the [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/configuration/). + +### Optionally Running the Default Engine + +The Alloy Collector Distro includes the option to run pipelines using the Default Engine alongside the OTel Engine using the built in Alloy Engine extension. More information on how to run the extension can be found [here](https://github.com/grafana/alloy/blob/main/extension/alloyengine/README.md) + +This will run a Default Engine pipeline _in parallel_ to the OTel Engine pipeline - the two pipelines cannot natively interact. + +### Available Components + +The included components are based off the upstream core distribution, in order to ensure that full end-to-end pipelines are accessible for most use cases. In addition to upstream components, we also integrate some of our own components that enable functionality to work well within the Alloy ecosystem. + +To view the full list of components and their versioning, please refer to the [OCB manifest](https://github.com/grafana/alloy/blob/main/collector/builder-config.yaml) + +## Examples + +### Running with OTel Engine only + +This example runs the OTel Engine without the Alloy Engine extension: + +```shell +alloy otel --config=config.yaml +``` + +Example `config.yaml`: + +```yaml +receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + +processors: + batch: + +exporters: + debug: + +service: + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [debug] +``` + +### Running with OTel Engine and Alloy Engine extension + +This example runs both the OTel Engine and the Alloy Engine extension in parallel: + +```shell +alloy otel --config=config.yaml +``` + +Example `config.yaml`: + +```yaml +extensions: + alloyengine: + config: + file: path/to/alloy-config.alloy + flags: + server.http.listen-addr: 0.0.0.0:12345 + stability.level: experimental + +receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + +processors: + batch: + +exporters: + debug: + +service: + extensions: [alloyengine] + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [debug] +``` + +## Related documentation +* [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/): Official OpenTelemetry Collector documentation. + + diff --git a/docs/sources/reference/cli/run.md b/docs/sources/reference/cli/run.md index 29eeb178e99..f1fca370831 100644 --- a/docs/sources/reference/cli/run.md +++ b/docs/sources/reference/cli/run.md @@ -11,7 +11,7 @@ weight: 300 # `run` -The `run` command runs {{< param "PRODUCT_NAME" >}} in the foreground until an interrupt is received. +The `run` command runs the {{< param "PRODUCT_NAME" >}} Default Engine in the foreground until an interrupt is received. ## Usage