otelij

The purpose of this repo is to help debug OpenTelemetry by allowing to generate span an send it to an OpenTelemetry collector while having full control over the span and how it is sent (OTLP, Jaeger, HTTP, gRPC etc..)

How to run

To send a span you will need to run the following

docker run -e OTEL_TRACES_EXPORTER=otlp -e OTEL_EXPORTER_OTLP_PROTOCOL=grpc public.ecr.aws/x3s3n8k7/otelij

This will start the otel debugger, send a single span with the configured exporter, and terminate when exporting is settled.
In case no error occurred you should see the following: Exported successfully..
In case of error, it would print the error message.

Note

In case you want to send spans to localhost, you can solve it with 2 options:

1. Add --network host to docker command, e.g., docker run --network host public.ecr.aws/x3s3n8k7/otelij
2. Replace localhost (in the relevant endpoint) with host.docker.internal instead, e.g., docker run -e OTEL_EXPORTER_OTLP_ENDPOINT==https://host.docker.internal:4317 public.ecr.aws/x3s3n8k7/otelij

Exporting spans

Otelij exporter is using the same exporter environment variables specification as described in OpenTelemetry specification. In order to control the endpoint/protocol/headers/resources and other built in exporter stuff, you can just use the same env as you see in the specification.

Usage

In order to use this tool there are some environment variables that you might need to set:

1. OTEL_TRACES_EXPORTER (optional) - valid options are [otlp, jaeger, zipkin, stdout], default is otlp
2. OTEL_EXPORTER_OTLP_PROTOCOL (optional [relevant for otlp exporter]) - valid options are [grpc, http/protobuf, http/json], default is grpc
3. OTEL_EXPORTER_JAEGER_PROTOCOL (optional [relevant for jaeger exporter]) - valid options are [http/thrift.binary, udp/thrift.compact] - default is http/thrift.binary
4. Dynamic span data (all optional):
   1. OTEL_SPAN_NAME - string. default will be Otelij debug span
   2. OTEL_SPAN_ATTRIBUTES - key values pair - comma delimited, e.g., attribute1=value1,attribute2=value2. default is no attributes
   3. OTEL_SPAN_KIND - span kind, valid options are: [internal, server, client, producer, consumer]. default is internal
   4. OTEL_SPAN_STATUS - span status, valid options are: [unset, error, ok]. default is unset.
   5. OTEL_SPAN_STATUS_MESSAGE - free text for description of span status. default is empty.
   6. OTEL_SPAN_DURATION_SEC - span duration to set in seconds. default is 1, usage as following OTEL_SPAN_DURATION_SEC=5.
5. Add link to another trace (optional)
   1. OTEL_SPAN_LINK_TRACE_ID (mandatory) - in case you want to link this span to another trace. default is none.
   2. OTEL_SPAN_LINK_SPAN_ID (mandatory) - span id to link to. default is none.
   3. OTEL_SPAN_LINK_TRACE_FLAGS - byte (currently only 1 bit to represent sampled/not sampled). default is 1.
   4. OTEL_SPAN_LINK_REMOTE - boolean, if link propagated from a remote parent.
   5. OTEL_SPAN_LINK_ATTRIBUTES - link attributes (same structure as OTEL_SPAN_ATTRIBUTES)

Examples

otlp env specification

otlp with grpc

docker run -e OTEL_TRACES_EXPORTER=otlp \
 -e OTEL_EXPORTER_OTLP_ENDPOINT=https://my-endpoint.io:4317 \
 -e OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
 -e OTEL_EXPORTER_OTLP_HEADERS=Authorization\=SOME_TOKEN \
 -e OTEL_RESOURCE_ATTRIBUTES=attribute1\=value1,attribute2\=value2 \
 -e OTEL_SERVICE_NAME=MyServiceName \
 public.ecr.aws/x3s3n8k7/otelij

otlp with http/protobuf

docker run -e OTEL_TRACES_EXPORTER=otlp \
 -e OTEL_EXPORTER_OTLP_ENDPOINT=https://my-endpoint.io:4318 \
 -e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
 -e OTEL_EXPORTER_OTLP_HEADERS=Authorization\=SOME_TOKEN \
 -e OTEL_RESOURCE_ATTRIBUTES=attribute1\=value1,attribute2\=value2 \
 -e OTEL_SERVICE_NAME=MyServiceName \
 public.ecr.aws/x3s3n8k7/otelij

with span data

docker run -e OTEL_TRACES_EXPORTER=otlp \
 -e OTEL_EXPORTER_OTLP_ENDPOINT=https://my-endpoint.io:4318 \
 -e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
 -e OTEL_EXPORTER_OTLP_HEADERS=Authorization\=SOME_TOKEN \
 -e OTEL_RESOURCE_ATTRIBUTES=attribute1\=value1,attribute2\=value2 \
 -e OTEL_SERVICE_NAME=MyServiceName \
 -e OTEL_SPAN_NAME=TestSpan \
 -e OTEL_SPAN_KIND=server \
 -e OTEL_SPAN_STATUS=ok \
 -e OTEL_SPAN_ATTRIBUTES=span.attr\=val1,span.attr2\=val2 \
 public.ecr.aws/x3s3n8k7/otelij

jaeger env specification

with udp/thrift.compact

docker run -e OTEL_TRACES_EXPORTER=jaeger \
 -e OTEL_EXPORTER_JAEGER_PROTOCOL=udp/thrift.compact \
 -e OTEL_EXPORTER_JAEGER_AGENT_HOST=localhost \
 -e OTEL_EXPORTER_JAEGER_AGENT_PORT=6831 \
 -e OTEL_RESOURCE_ATTRIBUTES=attribute1\=value1,attribute2\=value2 \
 -e OTEL_SERVICE_NAME=JaegerServiceName \
 public.ecr.aws/x3s3n8k7/otelij

with http/thrift.binary

docker run -e OTEL_TRACES_EXPORTER=jaeger \
 -e OTEL_EXPORTER_JAEGER_PROTOCOL=http/thrift.binary \
 -e OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces \
 -e OTEL_EXPORTER_JAEGER_AGENT_PORT=6831 \
 -e OTEL_RESOURCE_ATTRIBUTES=attribute1\=value1,attribute2\=value2 \
 -e OTEL_SERVICE_NAME=JaegerServiceName \
 public.ecr.aws/x3s3n8k7/otelij

zipkin env specification

docker run -e OTEL_TRACES_EXPORTER=zipkin \
 -e OTEL_EXPORTER_ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans \
 -e OTEL_SERVICE_NAME=JaegerServiceName \
 public.ecr.aws/x3s3n8k7/otelij

with link

docker run -e OTEL_TRACES_EXPORTER=otlp \
 -e OTEL_EXPORTER_OTLP_ENDPOINT=https://my-endpoint.io:4318 \
 -e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
 -e OTEL_EXPORTER_OTLP_HEADERS=Authorization\=SOME_TOKEN \
 -e OTEL_RESOURCE_ATTRIBUTES=attribute1\=value1,attribute2\=value2 \
 -e OTEL_SERVICE_NAME=MyServiceName \
 -e OTEL_SPAN_NAME=TestSpan \
 -e OTEL_SPAN_KIND=server \
 -e OTEL_SPAN_STATUS=ok \
 -e OTEL_SPAN_ATTRIBUTES=span.attr\=val1,span.attr2\=val2 \
 -e OTEL_SPAN_LINK_SPAN_ID=d6583451bafe66cb \
 -e OTEL_SPAN_LINK_TRACE_ID=d18ae83289fb43df3f8570bcb5c3177c \
 public.ecr.aws/x3s3n8k7/otelij