Observability and Tracing¶

Use this guide when local runs work, but traces or diagnostic output are not showing up where you expect them.

Choose The Trace Target¶

Target	Use when	Configuration surface
LangSmith cloud	You want hosted LangChain or LangGraph traces.	`LANGSMITH_*` variables in `.env` or the shell.
AgentSeek console	You want local CLI diagnostic spans and events.	`AGENTSEEK_CONSOLE=true`.
Phoenix	You use `langchain/default` or `langchain/agentic-rag-hybrid` and want local OpenTelemetry traces.	`AGENTSEEK_OTEL_*` variables and the template compose stack.

These targets are independent. Enabling one does not send data to the others.

For deepagents/sandbox, tracing is also independent of the sandbox provider. Daytona is the default sandbox backend. LangSmith Sandbox remains a charged alternative. A Daytona-backed agent can set LANGSMITH_TRACING=true and a LANGSMITH_API_KEY to send traces without switching AGENTSEEK_SANDBOX_PROVIDER. A LangSmith Sandbox user can leave tracing disabled.

Configure LangSmith Cloud Tracing¶

Set the LangSmith variables used by LangChain and LangGraph templates.

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=<your-langsmith-api-key>
LANGSMITH_PROJECT=<your-project-name>

Use LANGSMITH_ENDPOINT when your API key belongs to a non-default region. For APAC keys, configure the APAC endpoint.

LANGSMITH_ENDPOINT=https://apac.api.smith.langchain.com

The LangSmith observability quickstart documents the same regional endpoint behavior: non-US regions need LANGSMITH_ENDPOINT, or the API key may not authenticate against the default endpoint.

See the report in ob-labs/agentseek#83 for the APAC failure mode that motivated this guide.

Diagnose Local Studio Without Cloud Traces¶

Local Studio or a local thread page can show runs from your local development server even when cloud trace ingestion is failing.

Use this checklist when Studio is visible but LangSmith cloud traces are missing.

Check	What to fix
`LANGSMITH_TRACING` is not `true`	Enable tracing in the same environment that starts the app.
`LANGSMITH_API_KEY` is empty or from another region	Use a key from the target LangSmith region.
`LANGSMITH_ENDPOINT` is missing for APAC or another non-default region	Set the regional endpoint explicitly.
`LANGSMITH_PROJECT` is different from the dashboard project you opened	Open the configured project or change the variable.
The app process does not load `.env`	Export the variables in the shell that starts the app.

Treat local Studio visibility as a local runtime signal. Treat cloud traces as a separate ingestion signal.

Enable AgentSeek Console Output¶

Set AGENTSEEK_CONSOLE=true when you want AgentSeek CLI spans and events rendered locally through Logfire console output.

AGENTSEEK_CONSOLE=true

AgentSeek configures Logfire with send_to_logfire=False, so this does not upload data to Logfire cloud. It only changes local console rendering for the AgentSeek CLI process.

Use Phoenix In `langchain/default`¶

The langchain/default template includes local OpenTelemetry export to Phoenix. The generated app registers tracing in the LangChain application process. Bub and the gateway only forward messages.

The compose stack sends spans to Phoenix from inside the app container.

AGENTSEEK_OTEL_ENABLED=true
AGENTSEEK_OTEL_SERVICE_NAME=<project-slug>
AGENTSEEK_OTEL_PROJECT_NAME=<project-slug>
AGENTSEEK_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://phoenix:6006/v1/traces

For non-compose runs, point the endpoint at localhost instead.

AGENTSEEK_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:6006/v1/traces

The template compose stack uses ghcr.io/agentseek-ai/agentseek-phoenix:main for Phoenix and persists Phoenix data through OceanBase seekdb (quay.io/oceanbase/seekdb:latest). Override the images with AGENTSEEK_PHOENIX_IMAGE and OCEANBASE_SEEKDB_IMAGE.

Use Phoenix In `langchain/agentic-rag-hybrid`¶

The hybrid template keeps agentseek dev lightweight with uv, langgraph dev, and the Vite frontend. Phoenix is opt-in:

agentseek task phoenix

Then set OTEL in .env before starting agentseek dev.

AGENTSEEK_OTEL_ENABLED=true
AGENTSEEK_OTEL_SERVICE_NAME=<project-slug>
AGENTSEEK_OTEL_PROJECT_NAME=<project-slug>
AGENTSEEK_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:6006/v1/traces

The generated custom route /custom/observability reports the active OTEL endpoint, Phoenix URL, and Phoenix OceanBase seekdb URL. Phoenix trace storage uses the compose stack, while hybrid retrieval remains on embedded SeekDB through langchain-oceanbase.