Send your first trace

Go from a new account to a trace in Tracix: create a workspace, create an ingest key, and point a service's OpenTelemetry SDK at the workspace. Most of the time goes into the workspace starting up, which usually takes about four minutes.

Before you begin

• A Tracix account. Sign up to create one; you become the Owner of a new organization.
• A service you can start and send a request to. The steps below show Node.js, Python and Java. The workspace's Setup page also has instructions for .NET, Go, Ruby, PHP, C++, Rust, Swift and Erlang/Elixir.

Send a trace

1. 1

   Create a workspace

   In the console at https://cloud.tracix.io, open Workspaces and select New workspace. Choose Tracix-managed, then Amazon Web Services and the region, enter a Display name such as Production, and select Create workspace.

   The workspace's page shows the provisioning progress. Wait until the status changes to active. Create a workspace explains each choice in the wizard.

2. 2

   Open the workspace

   Select Open in app.tracix on the workspace's page, or open on its card under Workspaces. The workspace opens at its own address, such as https://production-a7k3p2q9.app.tracix.io, and signs you in with your console session.

3. 3

   Create an ingest key

   In the workspace, open Applications › APM & Traces and select the Setup tab. Under Ingest keys, select New key, enter a Name such as checkout-api, leave Environment set to production, and select Create key.

   The key starts with apm_. Copy it and keep it somewhere safe now: Tracix shows it only once. Creating keys needs the workspace Admin role, which you have in a workspace you created.

4. 4

   Point your service at the workspace

   The Setup page builds these commands for you: choose where the service runs, its language and how to instrument it, and it fills in your endpoint, and the key you just created until you leave or reload the page. To run them yourself instead, replace <workspace> with your workspace ID, the part of the address after the name (a7k3p2q9 in the example), and <ingest key> with your key.

   Node.jsPythonJava

   InstallCopy

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

   Run with auto-instrumentationCopy

   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

5. 5

   Send a request and find the trace

   Send your service one request. The Setup page checks for new data every 15 seconds. Waiting for the first span changes to Traces from checkout-api, with the number of spans, how long ago the last one arrived and the SDK's language, and an Open checkout-api link appears.

   Select Open checkout-api to see the service, or open the Traces tab to see the trace itself. Runtime metrics and logs show up in the same checks as they arrive.

What the settings do

• OTEL_EXPORTER_OTLP_ENDPOINT is your workspace's OTLP/HTTP endpoint, https://otlp-http-<workspace>.app.tracix.io. It uses TLS on port 443, so don't add a port. The SDK adds the /v1/traces, /v1/metrics and /v1/logs paths itself.
• OTEL_EXPORTER_OTLP_HEADERS sends your ingest key with every export, as x-tracix-ingest-key=<ingest key>.
• OTEL_EXPORTER_OTLP_PROTOCOL must be http/protobuf for this endpoint. Some SDKs default to gRPC, which it refuses.
• OTEL_SERVICE_NAME is the service name APM shows.
• OTEL_RESOURCE_ATTRIBUTES sets the environment, deployment.environment.name. Spans that don't set one get the ingest key's environment.

For an SDK or collector that exports over gRPC, use https://otlp-<workspace>.app.tracix.io with OTEL_EXPORTER_OTLP_PROTOCOL=grpc and the same header. The Gateway endpoints card on the Setup page shows both endpoints for your workspace.

If no trace arrives

• The Ingest key check says the key is paused. Resume the key under Ingest keys, then send another request.
• HTTP 415 errors in your service's log. The SDK is sending gRPC to the OTLP/HTTP endpoint. Set OTEL_EXPORTER_OTLP_PROTOCOL to http/protobuf, or switch to the gRPC endpoint.
• Authentication errors in your service's log. Check that the header is exactly x-tracix-ingest-key=<ingest key> and that the key is active. A new or resumed key starts working within about 30 seconds.
• Nothing yet, and no errors. Make sure the service started with the variables set and received a request after it started, then select Check again on the Setup page.

Next steps