# Latitude quickstart

Latitude is an open-source platform for monitoring and improving production AI agents. Choose one setup route below to send your first trace.

## Choose a route

| Situation | Recommended route |
| --- | --- |
| A coding agent can edit and run the application | Latitude setup skill |
| TypeScript or JavaScript application | TypeScript SDK |
| Python 3.11+ application | Python SDK |
| Another language or an existing OpenTelemetry pipeline | OTLP over HTTP |
| An agent needs to inspect or manage Latitude | Latitude MCP |

## Required inputs

For an existing Latitude account:

- `LATITUDE_API_KEY`: Create an API key in Latitude project settings.
- `LATITUDE_PROJECT_SLUG`: Copy the project slug from project settings or the project URL.
- A real application path that performs an LLM or agent call.
- The LLM provider or framework SDK used by the application.

Keep API keys out of source control and agent chat transcripts.

## Route 1: coding-agent setup

This is the fastest supported route.

Paste this prompt into Claude Code, Cursor, Codex, Windsurf, OpenCode, or another coding agent:

```text
Install the `latitude-setup` skill from `github.com/latitude-dev/skills`, and use it to add Latitude tracing to this app following best practices.
```

The skill detects the application's providers and OpenTelemetry setup, installs the appropriate integration, runs real application code, and verifies that traces arrive.

For an existing Latitude account, the agent can also install the `latitude-telemetry` skill and use the provided API key and project slug.

Canonical instructions:

- https://docs.latitude.so/getting-started/skills.md
- https://docs.latitude.so/telemetry/start-tracing.md
- https://github.com/latitude-dev/skills

## Route 2: TypeScript or JavaScript SDK

Package:

```text
@latitude-data/telemetry
```

Requirements:

- `LATITUDE_API_KEY`
- `LATITUDE_PROJECT_SLUG`
- The provider or framework SDK module used by the application
- Latitude initialized before LLM clients and calls
- `latitude.ready` awaited before calls begin
- A flush or shutdown before short-lived processes exit

The SDK uses OpenTelemetry and can attach to an existing compatible tracing setup. Use `capture()` around a request, conversation turn, or agent run to add user IDs, session IDs, tags, and metadata. `capture()` adds context to instrumented operations. It does not create spans by itself.

Current setup instructions:

- https://docs.latitude.so/telemetry/typescript.md
- https://docs.latitude.so/telemetry/start-tracing.md

## Route 3: Python SDK

Package:

```text
latitude-telemetry
```

Requirements:

- Python 3.11 or later
- `LATITUDE_API_KEY`
- `LATITUDE_PROJECT_SLUG`
- The provider or framework SDK module used by the application
- Latitude initialized before LLM calls
- A flush or shutdown before short-lived processes exit

The SDK uses OpenTelemetry and can attach to an existing tracing provider. Use `capture()` to add user IDs, session IDs, tags, and metadata to instrumented operations.

Current setup instructions:

- https://docs.latitude.so/telemetry/python.md
- https://docs.latitude.so/telemetry/start-tracing.md

## Route 4: OTLP for any language

Use this route for Go, Java, Ruby, Rust, .NET, Elixir, PHP, or another OpenTelemetry-instrumented application.

| Field | Value |
| --- | --- |
| Protocol | OTLP over HTTP |
| Method | `POST` |
| Endpoint | `https://ingest.latitude.so/v1/traces` |
| Authorization | `Bearer <LATITUDE_API_KEY>` |
| Project header | `X-Latitude-Project: <LATITUDE_PROJECT_SLUG>` |
| Content type | `application/json` or `application/x-protobuf` |

Most OpenTelemetry SDKs can use:

```text
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.latitude.so/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer YOUR_API_KEY,X-Latitude-Project=YOUR_PROJECT_SLUG
```

A successful ingest request returns HTTP `202`.

To display model, token, message, cost, and latency details, spans must include OpenTelemetry Generative AI semantic convention attributes. Generic spans can appear without complete LLM metadata.

Canonical OTLP instructions and language examples:

- https://docs.latitude.so/telemetry/otel-exporter.md
- https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/

## Verify the setup

1. Trigger one real agent request or LLM call.
2. Open the Latitude project.
3. Go to **Traces**.
4. Confirm that the trace appears within a few seconds.
5. Open it and check the relevant spans, messages, tool calls, errors, model, tokens, and latency data.
6. For multi-turn agents, confirm that related traces share a session ID.
7. For short-lived scripts or jobs, flush telemetry before the process exits.

An OTLP `202` response confirms payload acceptance. Confirm that a nonempty trace was stored in the Traces view.

Common troubleshooting checks:

- Confirm that the API key belongs to the expected organization.
- Confirm that the project slug exists in that organization.
- Confirm that the instrumented SDK module is the same module used by the application.
- Confirm that the LLM call executes inside the active capture context.
- Consume streaming responses inside the capture context.
- Flush pending spans before process exit.
- Add `gen_ai.*` attributes when generic OTLP traces lack LLM details.

## Connect the Latitude MCP

The Latitude MCP lets coding agents read and manage a Latitude workspace.

| Field | Value |
| --- | --- |
| Server URL | `https://api.latitude.so/v1/mcp` |
| Transport | Remote Streamable HTTP |
| Authentication | OAuth |

During authentication:

1. Sign in to Latitude.
2. Select the organization the agent may access.
3. Approve the connection.

Connected agents and OAuth keys can be reviewed or revoked under **Settings → Keys → OAuth Keys**.

For Claude Code CLI:

```text
claude mcp add --transport http latitude https://api.latitude.so/v1/mcp --scope user
```

Then run Claude Code, open `/mcp`, select `latitude`, and authenticate.

Other agent-specific configurations:

- https://docs.latitude.so/getting-started/mcp.md

The MCP is useful for project discovery, trace verification, searches, signals, annotations, scores, datasets, keys, and other workspace operations. Telemetry reaches Latitude through an SDK or the OTLP ingestion endpoint.

## Deployment choice

- Latitude Cloud: Managed service at https://latitude.so
- Self-hosted: Docker Compose, Docker Swarm, or Kubernetes with Helm

Deployment documentation:

- https://docs.latitude.so/deployment/overview.md