# Send your first trace

Create a workspace, create an ingest key and point an OpenTelemetry SDK at your workspace's OTLP endpoint to see your first trace in Tracix.

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](https://cloud.tracix.io/signup) 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. 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](https://tracix.io/docs/get-started/create-a-workspace) explains each choice in the wizard.

**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. 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. 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.js

Install:

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

Run with auto-instrumentation:

```bash
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
```

#### Python

Install:

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

Run with auto-instrumentation:

```bash
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
```

#### Java

Download the agent:

```bash
curl -sSLO https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
```

Run with the agent:

```bash
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"

java -javaagent:./opentelemetry-javaagent.jar -jar app.jar
```

**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.

> **Treat the ingest key like a password**
>
> Anyone with the key can send data to your workspace. Keep it in a secret store or environment variable, not in source control or a container image.

## 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

- [Instrument more services](https://tracix.io/docs/collect/instrument/languages): Setup for every OpenTelemetry language

- [OTLP endpoint and ingest keys](https://tracix.io/docs/collect/instrument/otlp): Every endpoint, protocol and header

- [Install the collector](https://tracix.io/docs/collect/collector/install): Host metrics, logs, SNMP and more

- [Explore APM](https://tracix.io/docs/observe/apm): Services, traces, errors and the service map

- [Invite your team](https://tracix.io/docs/get-started/invite-your-team): Give teammates access to the workspace