Tags
Docker, docker compose, Fluent Bit, Go, logs, metrics, OpenTelemetry, signals, Telemetrygen, Traces
Testing OpenTelemetry configuration pipelines without resorting to instrumented applications, particularly for traces, can be a bit of a pain. Typically, you just want to validate you can get an exported/generated signal through your pipeline, which may not be the OpenTelemetry Collector (e.g., FluentBit or commercial solutions such as DataDog). This led to the creation of Tracegen, and then the larger Telementrygen.
You can use Tracegen or Telemetrygen by either downloading and running the Go app from GitHub or using the Docker file. But there are a couple of challenges:
- On initial investigation, these utilities appear wrapped up in the larger opentelemetry-collector-contrib. While potentially useful, shaking out your OTel pipelining is somewhat overkill.
- We can install the app locally with the following command, but then we need to set up Golang in the environment.
go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
- Fortunately, there is a Docker image that just contains the tool, but to use it, we need to know what the parameters are to override the container defaults. The only irritant is that you either need to mess about with the container to get at the information (i.e., run the — help options) or install the utility (the parameters are not in the GitHub docs), so we’ve teased out all the options into the following table.
The following table’s Signal column All means it can be applied to Metrics, Traces, or Logs. Otherwise we’ve named the signal type that the parameter can be used with.
Signal | Parameter/Flag | Description |
---|---|---|
Trace | –batch | Whether to batch traces (default true) |
All | –ca-cert string | Trusted Certificate Authority to verify server certificate |
Traces | –child-spans int | Client certificate file |
All | –client-key string | Client private key file |
All | –duration duration | For how long to run the test |
All | -h, –help {traces|metrics|logs} | help – with give you the basic help if no parameter is passed. Or the signal type help when used with the signal name e.g. telemetrygen traces --help |
All | –interval duration | Reporting interval (default 1s) |
Traces | –marshal | Whether to marshal trace context via HTTP headers |
All | –mtls | Whether to require client authentication for mTLS |
All | –otlp-attributes map[string]string | Custom resource attributes to use. The value is expected in the format key=”value”. Note you may need to escape the quotes when using the tool from a cli. Flag may be repeated to set multiple attributes (e.g --otlp-attributes key1=\"value1\" --otlp-attributes key2=\"value2\" ) |
All | –otlp-endpoint string | Destination endpoint for exporting logs, metrics and traces |
All | –otlp-header map[string]string | Custom header to be passed along with each OTLP request. The value is expected in the format key=”value”. Note you may need to escape the quotes when using the tool from a cli. Flag may be repeated to set multiple headers (e.g --otlp-header key1=\"value1\" --otlp-header key2=\"value2\" ) |
All | –otlp-http | Whether to use HTTP exporter rather than a gRPC one |
All | –otlp-http-url-path string | Which URL path to write to (default "/v1/traces" ) |
All | –otlp-insecure | Whether to enable client transport security for the exporter’s grpc or http connection |
All | –rate int | Approximately how many metrics per second each worker should generate. Zero means no throttling. |
Traces | –service string | Service name to use (default "telemetrygen" ) |
Traces | –size int | Desired minimum size in MB of string data for each trace generated. This can be used to test traces with large payloads, i.e. when testing the OTLP receiver endpoint max receive size. |
Traces | –span-duration duration | The duration of each generated span. (default 123µs) |
Traces | –status-code string | Status code to use for the spans, one of (Unset , Error , Ok ) or the equivalent integer (0,1,2) (default “0”) |
All | –telemetry-attributes map[string]string | Number of traces to generate in each worker (ignored if the duration is provided) (default 1) |
Traces | –traces int | Number of traces to generate in each worker (ignored if duration is provided) (default 1) |
All | –workers int | Number of workers (goroutines) to run (default of 1) |
Metrics | –metric-type metricType | Number of metrics to generate in each worker (ignored if the duration is provided) (default 1) |
Metrics | –metrics int | Number of logs to generate in each worker (ignored if the duration is provided) (default 1) |
Logs | –body string | Body of the log (default “the message”) |
Logs | –logs int | The severity number of the log ranges from 1 to 24 (inclusive) (default 9) |
Logs | –severity-number int32 | The severity number of the log ranges from 1 to 24 (inclusive) (default 9) |
Logs | –severity-text string | Severity text of the log (default “Info”) |
It is worth noting that while Tracegen has similar configuration parameters, they aren’t exactly the same in the CLI, often one dash rather than two in the name for example.
The following is a simple Docker compose file that can help you use the container to conduct local testing of your collector. In this configuration, we’re sending a trace to the host machine with HTTPS disabled.
services:
web:
image: ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest
network_mode: host
entrypoint:
[
"/telemetrygen",
"traces",
"--otlp-insecure",
"--otlp-endpoint",
"host.docker.internal:4317",
]
You must be logged in to post a comment.