Languages and SDKs

Tracix works with the upstream OpenTelemetry agents and SDKs: there is no Tracix SDK or wrapper to install. You point a standard SDK at your workspace, and the Setup page writes the exact commands for your platform, language and service.

Use the Setup page

In your workspace, open Applications › APM & Traces, then the Setup tab, and answer its questions:

1. Where does the service run? Host or VM, Docker, Kubernetes or AWS Lambda.
2. Language. Java, Kotlin, .NET, Node.js, Python, Go, Ruby, PHP, C++, Rust, Swift, Erlang/Elixir, or Other for any SDK that reads the standard OTEL_* variables.
3. How to instrument. The recommended method is marked Recommended. Methods that can't serve your language stay listed with the reason.
4. Enter the Service name, an optional Service group and, on Kubernetes, the Cluster name, and pick an Ingest key.

The commands update as you go, with your endpoint filled in. Ingest keys are shown only once, when you create them: a key you create on the page is filled into the commands until you leave or reload it, and otherwise the commands show YOUR_INGEST_KEY for you to replace with the key you saved. The Verify card beside them shows when the first traces, runtime metrics and logs arrive. If you have no ingest key yet, create one first: see OTLP endpoint and ingest keys.

Choose a method

An agent or SDK inside the process gives you full distributed traces, runtime metrics and logs. eBPF tracing needs no code, image or restart change, but runs on Linux only and doesn't link requests across services by default.

On Kubernetes, the Operator is recommended for Java, Kotlin, .NET, Node.js and Python. For Go, building the SDK into the image is recommended, because the Operator injects Go as an eBPF sidecar that sends traces only. The Operator can't inject Ruby, PHP, C++, Rust, Swift or Erlang/Elixir, so build the SDK into the image for those.

What each language collects

What the Setup page installs, and what you change in your code:

What gets traced, and which logs are sent:

The Ruby, Rust and Erlang/Elixir SDKs mark parts of their own support as experimental or beta upstream. Data from every method lands on the same pages: Services, Traces and each service's Runtime tab.

Example: run a service on a host

Install the agent, set the exporter variables and start the service:

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

export OTEL_SERVICE_NAME="checkout-api"
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.0.0,deployment.environment.name=production"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-http-<workspace>.app.tracix.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-tracix-ingest-key=<ingest key>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

node app.js

pip install opentelemetry-distro opentelemetry-exporter-otlp opentelemetry-instrumentation-system-metrics
opentelemetry-bootstrap -a install

export OTEL_SERVICE_NAME="checkout-api"
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.0.0,deployment.environment.name=production"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-http-<workspace>.app.tracix.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-tracix-ingest-key=<ingest key>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED="true"

opentelemetry-instrument python app.py

For the other languages, the Setup page shows the same steps with your endpoint and key filled in.

Docker

On Docker, the Setup page gives you a Dockerfile that builds the agent or SDK into the image, and a docker run command. The endpoint and ingest key are passed at run time, so they never end up in the image:

docker run -d --name checkout-api \
-e OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-http-<workspace>.app.tracix.io" \
-e OTEL_EXPORTER_OTLP_HEADERS="x-tracix-ingest-key=<ingest key>" \
checkout-api:latest

Kubernetes with the OpenTelemetry Operator

The OpenTelemetry Operator injects the agent into pods as they start, so you don't change your images. It is upstream software you run in your cluster; Tracix only gives it the endpoint and key.

1. 1

   Install the Operator

   Once per cluster, install it with Helm. Its admission webhook needs cert-manager, or the chart's self-generated certificate. Skip this if the Operator already runs in the cluster.

   bashCopy

   helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
   helm repo update open-telemetry
   helm install opentelemetry-operator open-telemetry/opentelemetry-operator \
   --namespace opentelemetry-operator-system --create-namespace \
   --set manager.collectorImage.repository=ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-k8s

2. 2

   Store the ingest key in the application's namespace

   bashCopy

   kubectl create secret generic tracix-apm -n <app-namespace> \
   --from-literal=otlp-headers="x-tracix-ingest-key=<ingest key>"

3. 3

   Create the Instrumentation resource

   The Setup page writes a tracix-apm.yaml with an Instrumentation named tracix-apm. It sends traces, metrics and logs over OTLP/HTTP to your workspace, reads the header from the secret, and sets deployment.environment.name and k8s.cluster.name. Apply it in the application's namespace with kubectl apply -n <app-namespace> -f tracix-apm.yaml.

4. 4

   Opt workloads in

   Annotate the namespace, or one Deployment's pod template, for your language, then restart its pods:

   bashCopy

   kubectl annotate namespace <app-namespace> \
   instrumentation.opentelemetry.io/inject-java=tracix-apm
   kubectl rollout restart deployment -n <app-namespace>

   Use inject-dotnet, inject-nodejs or inject-python for those languages. Alpine-based Python and .NET images need an extra pod annotation, which the Setup page shows.

Services are named after their Deployment, StatefulSet or DaemonSet. To name one differently, set the resource.opentelemetry.io/service.name annotation on its pod template.

The Setup page can also give you OpenTelemetry Collectors for the Operator to run, which collect container logs, kubelet metrics and cluster events with the same ingest key. To collect those with the Tracix Collector instead, install it with Helm on a policy with the Kubernetes integration.

AWS Lambda

For Java, Kotlin, Node.js, Python and Ruby, add the OpenTelemetry Lambda layer for your runtime and set the function's environment:

The OpenTelemetry Lambda project publishes the layer ARNs for each region. For .NET and Go, the Setup page shows the handler wrapper to add; for the other languages, set the SDK up in the function's init code and flush it before each invocation returns. The layer adds some cold-start time.

Environment variables

Every in-process setup on the Setup page sets these:

service.version=1.0.0 in the generated commands is a placeholder: set it to the version you release. tracix.service_group.name puts the service in a service group; the key's default group applies when you leave it out.

Next steps