otelgen

A tool to generate synthetic OpenTelemetry logs, metrics and traces.

Why

Often synthetics are used to validate certain configurations, to ensure that that systems operate as expected. Operating OpenTelemetry Collectors is often a complex task, which entails tuning many facets such as Receivers, Proccessors and Exporters.

otelgen allows you to quickly validate these configurations using the OpenTelemetry Protocol Specification, which supports both OTLP/gRPC and OTLP/HTTP using the OTLP Receiver.

Supported Signals

The following specifications are supported.

• Traces: Yes
  • Scenarios to simulate differnt trace patterns
  • Span Events
  • Span Links
• Metrics: Yes
  • Metric Types:
    • Exponential Histogram
    • Guage
    • Histogram
    • Sum
  • Exemplars
• Logs: Yes
  • Log Levels
  • Log Attributes
  • Trace Context Correlation

Getting Started

Installing otelgen is possible via several methods. It can be insatlled via brew, an binary downloaded from GitHub Releases, or running it as a distroless multi-arch docker image.

brew

Install brew and then run:

brew install krzko/tap/otelgen

Download Binary

Download the latest version from the Releases page.

Docker

To see all the tags view the Packages page.

Rn the container via the following command:

docker run --rm ghcr.io/krzko/otelgen:latest -h

Run

Running otelgen will generate this help:

NAME:
   otelgen - A tool to generate synthetic OpenTelemetry logs, metrics and traces

USAGE:
   otelgen [global options] command [command options] [arguments...]

VERSION:
   develop

COMMANDS:
   logs, l     Generate logs
   metrics, m  Generate metrics
   traces, t   Generate traces
   help, h     Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --duration value, -d value           duration in seconds (default: 0)
   --header value                       additional headers in 'key=value' format  (accepts multiple inputs)
   --help, -h                           show help (default: false)
   --insecure, -i                       whether to enable client transport security (default: false)
   --log-level value                    log level used by the logger, one of: debug, info, warn, error (default: "info")
   --otel-exporter-otlp-endpoint value  target URL to exporter endpoint
   --protocol value, -p value           the transport protocol, one of: grpc, http (default: "grpc")
   --rate value, -r value               rate in seconds (default: 5)
   --service-name value, -s value       service name to use (default: "otelgen")
   --version, -v                        print the version (default: false)

Signals

otelgen emits three types of signals, logs, metrics and traces. Each signal has a different set of options, which can be configured via the command line.

Traces

The otelgen traces command supports two types of traces, single and multi, the difference being, sometimes you just want to send a single trace to validate a configuration. Multi will allow you configure the duration and rate.

Here is an example, of how to generate a trace using single, with using secure transport:

$ otelgen --otel-exporter-otlp-endpoint otelcol.foo.bar:443 traces single

{"level":"info","ts":1658747062.525185,"caller":"cli/traces.go:90","msg":"starting gRPC exporter"}
{"level":"info","ts":1658747062.710507,"caller":"traces/config.go:58","msg":"generation of traces isn't being throttled"}
{"level":"info","ts":1658747062.7106712,"caller":"traces/traces.go:43","msg":"starting traces","worker":0}
{"level":"info","ts":1658747062.710735,"caller":"traces/traces.go:79","msg":"Trace","worker":0,"traceId":"9481f4c1a9099079c49ed14af2739b6d"}
{"level":"info","ts":1658747062.710753,"caller":"traces/traces.go:80","msg":"Parent Span","worker":0,"spanId":"fd76b9e4265aecfc"}
{"level":"info","ts":1658747062.7107708,"caller":"traces/traces.go:81","msg":"Child Span","worker":0,"spanId":"02267d8d1342d63a"}
{"level":"info","ts":1658747062.710814,"caller":"traces/traces.go:92","msg":"traces generated","worker":0,"traces":2}
{"level":"info","ts":1658747062.710835,"caller":"cli/traces.go:108","msg":"stop the batch span processor"}
{"level":"info","ts":1658747062.742642,"caller":"cli/traces.go:99","msg":"stopping the exporter"}

If you're running a collector on localhost, use --insecure to enable h2c for OTLP/gRPC (4317/tcp) and http for OTLP/HTTP (4318/tcp), of how to generate a trace using single, with using insecure transport:

$ otelgen --otel-exporter-otlp-endpoint localhost:4317 --insecure traces single

Here is an example, of how to generate a trace using multi, also, run -h to view the default values for each flag:

$ otelgen --otel-exporter-otlp-endpoint otelcol.foo.bar:443 --duration 10 --rate 1 traces multi

{"level":"info","ts":1658747148.7179039,"caller":"cli/traces.go:203","msg":"starting gRPC exporter"}
{"level":"info","ts":1658747148.908546,"caller":"traces/config.go:60","msg":"generation of traces is limited","per-second":1}
{"level":"info","ts":1658747148.908957,"caller":"traces/config.go:81","msg":"generation duration","seconds":10}
{"level":"info","ts":1658747148.910296,"caller":"traces/traces.go:43","msg":"starting traces","worker":0}
{"level":"info","ts":1658747148.91046,"caller":"traces/traces.go:79","msg":"Trace","worker":0,"traceId":"e299fc2461e04ee3c97d4f59e9b5f67a"}
{"level":"info","ts":1658747148.910481,"caller":"traces/traces.go:80","msg":"Parent Span","worker":0,"spanId":"0cefe413f4f5559a"}
{"level":"info","ts":1658747148.910497,"caller":"traces/traces.go:81","msg":"Child Span","worker":0,"spanId":"0ff83ff196aa83de"}
{"level":"info","ts":1658747148.91053,"caller":"traces/traces.go:43","msg":"starting traces","worker":0}
{"level":"info","ts":1658747149.9106922,"caller":"traces/traces.go:79","msg":"Trace","worker":0,"traceId":"9161121ffb377ef3e7b1d1efdb88c5d3"}
{"level":"info","ts":1658747149.910769,"caller":"traces/traces.go:80","msg":"Parent Span","worker":0,"spanId":"0aab1b9d6535bb84"}
{"level":"info","ts":1658747149.910798,"caller":"traces/traces.go:81","msg":"Child Span","worker":0,"spanId":"665b66edc4c7e26e"}
...

If you need to pass in additional HTTP headers to allow for authentication to vendor backends, simply utilise the --header key=value flag. The unit is a slice of headers so it accepts multiple headers during invocation. Such as:

$ otelgen --otel-exporter-otlp-endpoint api.vendor.xyz:443 \
    --header 'x-auth=xxxxxx' \
    --header 'x-dataset=xxxxxx' \
    traces single

Metrics

The otelgen metrics command supports many different metric types. Here is an example of how to generate metrics:

$ otelgen --otel-exporter-otlp-endpoint otelcol.foo.bar:443 metrics counter

{"level":"info","ts":1658746679.286242,"caller":"cli/metrics_counter.go:70","msg":"starting gRPC exporter"}
{"level":"info","ts":1658746679.46613,"caller":"cli/metrics_counter.go:87","msg":"Starting metrics generation"}
{"level":"info","ts":1658746679.466242,"caller":"metrics/config.go:59","msg":"generation of metrics is limited","per-second":5}
{"level":"info","ts":1658746679.467317,"caller":"metrics/metrics.go:47","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746684.4677298,"caller":"metrics/metrics.go:47","msg":"generating","name":"otelgen.metrics.counter"}
...

Here is an example, of how to limit the duration in seconds of a generation process:

$ otelgen --otel-exporter-otlp-endpoint otelcol.foo.bar:443 --duration 30 metrics counter

{"level":"info","ts":1658746721.598725,"caller":"cli/metrics_counter.go:70","msg":"starting gRPC exporter"}
{"level":"info","ts":1658746721.789262,"caller":"cli/metrics_counter.go:87","msg":"Starting metrics generation"}
{"level":"info","ts":1658746721.789321,"caller":"metrics/config.go:59","msg":"generation of metrics is limited","per-second":5}
{"level":"info","ts":1658746721.7894,"caller":"metrics/metrics.go:30","msg":"generation duration","seconds":30}
{"level":"info","ts":1658746721.789411,"caller":"metrics/metrics.go:40","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746726.7905679,"caller":"metrics/metrics.go:40","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746731.790965,"caller":"metrics/metrics.go:40","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746736.791102,"caller":"metrics/metrics.go:40","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746741.791389,"caller":"metrics/metrics.go:40","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746746.791574,"caller":"metrics/metrics.go:40","msg":"generating","name":"otelgen.metrics.counter"}
{"level":"info","ts":1658746751.791806,"caller":"cli/metrics_counter.go:79","msg":"stopping the exporter"}

If you need to pass in additional HTTP headers to allow for authentication to vendor backends, simply utilise the --header key=value flag. The unit is a slice of headers so it accepts multiple headers during invocation. Such as:

$ otelgen --otel-exporter-otlp-endpoint api.vendor.xyz:443 \
    --header 'x-auth=xxxxxx' \
    --header 'x-dataset=xxxxxx' \
    metrics counter

Logs

The otelgen logs command generates synthetic logs that simulate realistic workloads, useful for testing and validating observability pipelines.

$  otelgen --otel-exporter-otlp-endpoint localhost:4317 --insecure logs

2024-09-29T15:03:10.092+1000	INFO	logs/logs.go:63	generation of logs is limited	{"per-second": 5}
2024-09-29T15:03:10.093+1000	INFO	logs/logs.go:177	starting log generation	{"worker": 0, "worker_id": 0}
2024-09-29T15:03:18.976+1000	INFO	logs/logs.go:138	log generation completed	{"total_logs": 30}