This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.
Collect OpenTelemetry data and forward it to any OpenTelemetry-compatible endpoint
You can configure Alloy to collect OpenTelemetry-compatible data and forward it to any OpenTelemetry-compatible endpoint.
This topic describes how to:
- Configure OpenTelemetry data delivery.
- Configure batching.
- Receive OpenTelemetry data over OTLP.
Components used in this topic
- otelcol.auth.basic
- otelcol.exporter.otlp
- otelcol.exporter.otlphttp
- otelcol.processor.batch
- otelcol.receiver.otlp
Before you begin
- Ensure that you have basic familiarity with instrumenting applications with OpenTelemetry.
- Have a set of OpenTelemetry applications ready to push telemetry data to Alloy.
- Identify where Alloy writes received telemetry data.
- Be familiar with the concept of Components in Alloy.
Configure an OpenTelemetry Protocol exporter
Before components can receive OpenTelemetry data, you must have a component responsible for exporting the OpenTelemetry data. An OpenTelemetry exporter component is responsible for writing (exporting) OpenTelemetry data to an external system.
In this task, you will use the otelcol.exporter.otlp component to send OpenTelemetry data to a server using the OpenTelemetry Protocol (OTLP). After an exporter component is defined, you can use other Alloy components to forward data to it.
Tip
Refer to the list of available Components for the full list ofotelcol.exporter
components that you can use to export OpenTelemetry data.
To configure an otelcol.exporter.otlp
component for exporting OpenTelemetry data using OTLP, complete the following steps:
Add the following
otelcol.exporter.otlp
component to your configuration file:otelcol.exporter.otlp "<EXPORTER_LABEL>" { client { endpoint = "<HOST>:<PORT>" } }
Replace the following:
<EXPORTER_LABEL>
: The label for the component, such asdefault
. The label you use must be unique across allotelcol.exporter.otlp
components in the same configuration file.
<HOST>
: The hostname or IP address of the server to send OTLP requests to.
<PORT>
: The port of the server to send OTLP requests to.
If your server requires basic authentication, complete the following:
Add the following
otelcol.auth.basic
component to your configuration file:otelcol.auth.basic "<BASIC_AUTH_LABEL>" { username = "<USERNAME>" password = "<PASSWORD>" }
Replace the following:
<BASIC_AUTH_LABEL>
: The label for the component, such asdefault
. The label you use must be unique across allotelcol.auth.basic
components in the same configuration file.<USERNAME>
: The basic authentication username.<PASSWORD>
: The basic authentication password or API key.
Add the following line inside of the
client
block of yourotelcol.exporter.otlp
component:auth = otelcol.auth.basic.<BASIC_AUTH_LABEL>.handler
Replace the following:
<BASIC_AUTH_LABEL>
: The label for theotelcol.auth.basic
component.
If you have more than one server to export metrics to, create a new
otelcol.exporter.otlp
component for each additional server.
Note
otelcol.exporter.otlp
sends data using OTLP over gRPC (HTTP/2). To send to a server using HTTP/1.1, follow the preceding steps, but use theotelcol.exporter.otlphttp
component instead.
The following example demonstrates configuring otelcol.exporter.otlp
with authentication and a component that forwards data to it:
otelcol.exporter.otlp "default" {
client {
endpoint = "my-otlp-grpc-server:4317"
auth = otelcol.auth.basic.credentials.handler
}
}
otelcol.auth.basic "credentials" {
// Retrieve credentials using environment variables.
username = sys.env("BASIC_AUTH_USER")
password = sys.env("API_KEY")
}
otelcol.receiver.otlp "example" {
grpc {
endpoint = "127.0.0.1:4317"
}
http {
endpoint = "127.0.0.1:4318"
}
output {
metrics = [otelcol.exporter.otlp.default.input]
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}
For more information on writing OpenTelemetry data using the OpenTelemetry Protocol, refer to otelcol.exporter.otlp.
Configure batching
Production-ready Alloy configurations shouldn’t send OpenTelemetry data directly to an exporter for delivery. Instead, data is usually sent to one or more processor components that perform various transformations on the data.
Ensuring data is batched is a production-readiness step to improve data compression and reduce the number of outgoing network requests to external systems.
In this task, you will configure an otelcol.processor.batch component to batch data before sending it to the exporter.
Note
Refer to the list of available Components for the full list ofotelcol.processor
components that you can use to process OpenTelemetry data. You can chain processors by having one processor send data to another processor.
To configure an otelcol.processor.batch
component, complete the following steps:
Follow Configure an OpenTelemetry Protocol exporter to ensure received data can be written to an external system.
Add the following
otelcol.processor.batch
component into your configuration file:otelcol.processor.batch "<PROCESSOR_LABEL>" { output { metrics = [otelcol.exporter.otlp.<EXPORTER_LABEL>.input] logs = [otelcol.exporter.otlp.<EXPORTER_LABEL>.input] traces = [otelcol.exporter.otlp.>EXPORTER_LABEL>.input] } }
Replace the following:
<PROCESSOR_LABEL>
: The label for the component, such asdefault
. The label you use must be unique across allotelcol.processor.batch
components in the same configuration file.<EXPORTER_LABEL>
: The label for your existingotelcol.exporter.otlp
component.
To disable one of the telemetry types, set the relevant type in the
output
block to the empty list, such asmetrics = []
.To send batched data to another processor, replace the components in the
output
list with the processor components to use.
The following example demonstrates configuring a sequence of otelcol.processor
components before being exported.
otelcol.processor.memory_limiter "default" {
check_interval = "1s"
limit = "1GiB"
output {
metrics = [otelcol.processor.batch.default.input]
logs = [otelcol.processor.batch.default.input]
traces = [otelcol.processor.batch.default.input]
}
}
otelcol.processor.batch "default" {
output {
metrics = [otelcol.exporter.otlp.default.input]
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}
otelcol.exporter.otlp "default" {
client {
endpoint = "my-otlp-grpc-server:4317"
}
}
For more information on configuring OpenTelemetry data batching, refer to otelcol.processor.batch.
Configure an OpenTelemetry Protocol receiver
You can configure Alloy to receive OpenTelemetry metrics, logs, and traces. An OpenTelemetry receiver component is responsible for receiving OpenTelemetry data from an external system.
In this task, you will use the otelcol.receiver.otlp component to receive OpenTelemetry data over the network using the OpenTelemetry Protocol (OTLP). You can configure a receiver component to forward received data to other Alloy components.
Refer to the list of available Components for the full list of
otelcol.receiver
components that you can use to receive OpenTelemetry-compatible data.
To configure an otelcol.receiver.otlp
component for receiving OTLP data, complete the following steps:
Follow Configure an OpenTelemetry Protocol exporter to ensure received data can be written to an external system.
Optional: Follow Configure batching to improve compression and reduce the total amount of network requests.
Add the following
otelcol.receiver.otlp
component to your configuration file.otelcol.receiver.otlp "<LABEL>" { output { metrics = [<COMPONENT_INPUT_LIST>] logs = [<COMPONENT_INPUT_LIST>] traces = [<COMPONENT_INPUT_LIST>] } }
Replace the following:
<LABEL>
: The label for the component, such asdefault
. The label you use must be unique across allotelcol.receiver.otlp
components in the same configuration file.<COMPONENT_INPUT_LIST>
: A comma-delimited list of component inputs to forward received data to. For example, to send data to an existing batch processor component, useotelcol.processor.batch.PROCESSOR_LABEL.input
. To send data directly to an existing exporter component, useotelcol.exporter.otlp.EXPORTER_LABEL.input
.
To allow applications to send OTLP data over gRPC on port
4317
, add the following to yourotelcol.receiver.otlp
component.grpc { endpoint = "<HOST>:4317" }
Replace the following:
<HOST>
: A host to listen to traffic on. Use a narrowly scoped listen address whenever possible. To listen on all network interfaces, replace<HOST>
with0.0.0.0
.
To allow applications to send OTLP data over HTTP/1.1 on port
4318
, add the following to yourotelcol.receiver.otlp
component.http { endpoint = "<HOST>:4318" }
Replace the following:
<HOST>
: The host to listen to traffic on. Use a narrowly scoped listen address whenever possible. To listen on all network interfaces, replace<HOST>
with0.0.0.0
.
To disable one of the telemetry types, set the relevant type in the
output
block to the empty list, such asmetrics = []
.
The following example demonstrates configuring otelcol.receiver.otlp
and sending it to an exporter:
otelcol.receiver.otlp "example" {
grpc {
endpoint = "127.0.0.1:4317"
}
http {
endpoint = "127.0.0.1:4318"
}
output {
metrics = [otelcol.processor.batch.example.input]
logs = [otelcol.processor.batch.example.input]
traces = [otelcol.processor.batch.example.input]
}
}
otelcol.processor.batch "example" {
output {
metrics = [otelcol.exporter.otlp.default.input]
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}
otelcol.exporter.otlp "default" {
client {
endpoint = "my-otlp-grpc-server:4317"
}
}
For more information on receiving OpenTelemetry data using the OpenTelemetry Protocol, refer to otelcol.receiver.otlp.