Tracey productGet started

Start here / 15-minute path

Connect one agent. See the whole run.

This guide gets a single agent from OpenTelemetry export to a read-only Tracey investigation. It does not require changing where your agent is deployed.

Before you begin

Have access to a SigNoz workspace receiving traces, an agent service identity, and a non-production environment where you can safely test telemetry.

  • SigNoz endpoint and read credentials
  • A stable service name and environment for the agent
  • OpenTelemetry Collector or an OTLP-capable exporter
  • Permission to register the agent in Tracey

1. Connect SigNoz

Add SigNoz as Tracey’s observability backend. Tracey queries bounded traces, logs, metrics, and exceptions while leaving raw telemetry in SigNoz.

Start with read-only credentials. Connector readiness and missing permissions should be visible before you attempt an investigation.

2. Register the agent

Register the service identity that Tracey should recognize. Use a stable name across deployments and include the environment so production and staging cannot be confused.

service.name = "notes-agent-api"
deployment.environment = "staging"
tracey.agent.id = "notes-agent-api"

3. Emit a root agent-run span

Create one root span for the complete run. Child spans should represent routing, model calls, retrieval, tools, handoffs, side effects, and the final result.

agent.run
├── agent.route
├── gen_ai.chat
├── tool.call
├── mcp.request
└── agent.result

4. Verify the first run

Open Tracey and confirm the run has an identity, outcome, duration, trace ID, and enough child spans to explain the path. Incomplete telemetry should be visible as incomplete—not silently treated as healthy.

5. Ask a bounded question

Start with a read-only investigation such as “Why did this run fail?” Tracey should return evidence references, the systems queried, and any limitations that prevent a complete conclusion.

  • Which span or dependency failed?
  • What changed before the failure?
  • Which users or services are affected?

Next step: prepare, do not execute

Once investigations are reliable, connect Kubernetes in a non-production environment and preview a typed remediation plan. Keep the mode at Recommend until verification and rollback criteria are tested.