> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send OpenTelemetry from any app to Reliant

> Send traces, logs and metrics from an app in any language to Reliant's hosted OpenTelemetry backend: mint a token with forge obs init and set the variables.

By the end of this guide, an app that Forge did not build and does not deploy sends its traces, logs and metrics to Reliant, and you can read them with `reliant forge obs`. It can be in any language, on any infrastructure: you add an OpenTelemetry SDK and a few environment variables.

The variables are the standard OpenTelemetry ones, so there is no Reliant SDK to install. The token decides which organization and environment the data lands in.

## Before you begin

* A Reliant account in the organization the telemetry should belong to, with the `obs:write` permission to mint tokens. Owners and admins hold it.
* The `reliant` CLI v1.21.3 or later, which includes forge v1.6.1 ([install](https://docs.reliantlabs.io/getting-started/installation.md)). Your repository does not need a `forge.yaml`.
* Your own terminal and browser. Ingest tokens are minted by a person, so this cannot be run by an agent or a CI job.

**1. Sign in as yourself**

```bash terminal theme={null}
reliant forge cloud login
```

This opens your browser and stores a credential for Reliant's control plane.

**2. Register the environment and mint a token**

From the root of your app's repository, name the environments and the project to create or reuse:

```bash terminal theme={null}
reliant forge obs init prod --project shop --service checkout-api
```

In a repository with no Forge files, it asks before writing `deploy/envs/prod.yaml` (`--write-config` skips the question, `--no-write` writes nothing). Commit that file: every `obs` command reads the project from it.

```yaml deploy/envs/prod.yaml theme={null}
apiVersion: forge.dev/env/v1
project: "shop"
env: "prod"
control_plane: {}  # Reliant's control plane
observability:
  enabled: true
  destination: {token_from_control_plane: true}
```

It then prints the ingest token's name, id and expiry date, followed by an `export` line for each variable. The token is shown once and expires after 90 days at most.

**3. Set the variables where the app runs**

Store the header as a secret in your deploy system, never in the repository, and set the rest beside it:

```bash terminal theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.reliantapi.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <token>"
OTEL_SERVICE_NAME=checkout-api
OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.namespace=shop,service.version=$GIT_SHA"
```

Use the values `obs init` printed. Give each deployable its own `OTEL_SERVICE_NAME`. Set `service.version` to what you deploy, such as the git SHA or release tag: the issue list's "first seen in" and `obs check` both key on it. Keep `deployment.environment.name` equal to the env name you passed to `obs init`.

**4. Add an OpenTelemetry SDK**

Any SDK that reads the standard variables works. Zero-code instrumentation is the shortest path:

| Language | Install | Run |
| - | - | - |
| Node.js | `npm i @opentelemetry/api @opentelemetry/auto-instrumentations-node` | `node --require @opentelemetry/auto-instrumentations-node/register app.js` |
| Python | `pip install opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install` | `opentelemetry-instrument python app.py` |
| Java or Kotlin | download `opentelemetry-javaagent.jar` | `java -javaagent:opentelemetry-javaagent.jar -jar app.jar` |
| Go | `go.opentelemetry.io/otel` with `otlptracehttp` and `otelhttp` | wrap your handlers |

For errors to become issues, failed requests must set the span status to error and record the exception. The auto-instrumentation above does this for unhandled errors. Export logs over OTLP (`OTEL_LOGS_EXPORTER=otlp`) only if nothing already ships the app's stdout, or every line arrives twice.

**5. Check that telemetry arrives**

Deploy the app with the variables set, send it some requests, then:

```bash terminal theme={null}
reliant forge obs status prod
```

Before anything arrives, the env exists but is empty:

```text theme={null}
prod (cloud backend), 2026-11-20T08:28:39Z .. 2026-11-20T09:28:39Z
no promotion on record
telemetry: nothing received in the last 24h0m0s

no service traffic in the range
```

Once data arrives, the `telemetry` line shows when the newest log and span came in, and your service appears with its request rate, errors and p95. Then read the data itself:

```bash terminal theme={null}
reliant forge obs traces prod --errors
reliant forge obs logs prod --severity error
reliant forge obs issues prod
```

**6. Rotate the token before it expires**

Nothing renews a token. `list` marks one in its last 14 days with "expires soon: rotate it":

```bash terminal theme={null}
reliant forge obs tokens list prod
reliant forge obs tokens rotate <token-id> --grace 24h
```

`rotate` mints a replacement, and the old token keeps working for the grace period while you roll out the new header. `obs tokens create prod --name <label>` mints a separate token per cluster or CI system, and `obs tokens revoke <token-id> --reason leaked` cuts one off within minutes.

## What this does not do

* It does not build or deploy your app. The environment is registered as self-managed, and the platform never deploys there.
* There is no anonymous path. Reading telemetry needs a sign-in, and minting tokens needs a person with `obs:write`. A CI job can read with a token that has `obs:read` ([credentials](https://docs.reliantlabs.io/hosting/observability/forge-obs.md#credentials)).
* With no deploy recorded, `obs check` judges a new `service.version` from the first time telemetry showed it, and marks the result `marker INFERRED`. A canary or slow rollout moves that moment.
* A monitoring-only environment gets the built-in alerts (new and regressed issues, quota) and your organization's alert receivers. Per-environment alert rules come from a Forge-deployed environment's declaration ([dashboards and alerts](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md#alerts)).
* The ingest token is a server-side secret. Never ship it in a browser bundle or a mobile app.

## Troubleshooting

> [accordion] telemetry ingest tokens are minted, rotated and revoked by a person, not a machine credential
>
> `obs init` ran with an agent's or a pipeline's credential. Run it yourself in your own terminal after `reliant forge cloud login`. The refused run may still have registered the env and written `deploy/envs/prod.yaml`; running it again reuses both and only mints the token.

> [accordion] minting an ingest token needs a person who is a member of the organization holding the obs:write permission
>
> Your account lacks `obs:write`. Ask an owner or admin of the organization to grant it, or to run `obs init` for you.

> [accordion] telemetry: nothing received in the last 24h0m0s
>
> Check that the app's process actually has the variables, the protocol is `http/protobuf`, and the header reads `authorization=Bearer <token>` with no extra quotes. Check that the token is not revoked (`obs tokens list prod --all`).

> [accordion] env prod is declared in deploy/kcl/prod/main.k
>
> That env is deployed by Forge, which wires its telemetry for you. For a token for an app outside Forge's deploys, use `reliant forge obs tokens create prod`.

## Next steps

> [card] [Find which release introduced an error](https://docs.reliantlabs.io/guides/observability/find-release-that-caused-error.md)
>
> Trace an issue to its release and suspect commits.

> [card] [Bring an existing app to Forge](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md)
>
> Go further: let Forge build and deploy the same app.

> [card] [Debug production with an AI agent](https://docs.reliantlabs.io/guides/observability/debug-production-with-ai-agent.md)
>
> Point an agent at the same logs, traces and issues.

> [card] [Where the telemetry goes](https://docs.reliantlabs.io/hosting/observability/where-it-goes.md)
>
> Retention, usage and what the platform collects.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.