Quick Start Guide

Get started with Tracely.cc in under 5 minutes.

Prerequisites

Installation

Node.js / TypeScript

npm install @tracely/sdk
# or
yarn add @tracely/sdk

Python

pip install tracely-sdk

Go

go get github.com/tracely/tracely-go

Configuration

Basic Setup (Node.js)

import { Tracely } from '@tracely/sdk';

const tracely = new Tracely({
  apiKey: process.env.TRACELY_API_KEY,
  serviceName: 'my-service',
  environment: 'production'
});

// Auto-instrument your application
tracely.start();

Python Setup

from tracely import Tracely

tracely = Tracely(
    api_key=os.getenv('TRACELY_API_KEY'),
    service_name='my-service',
    environment='production'
)

tracely.start()

Distributed Tracing

Tracely automatically captures distributed traces across your entire system, from frontend requests to backend services and database queries.

Manual Instrumentation

// Create a custom span
const span = tracely.startSpan('process-payment');

try {
  // Your business logic
  const result = await processPayment(order);
  span.setTag('order.id', order.id);
  span.setTag('amount', order.total);
  return result;
} catch (error) {
  span.setTag('error', true);
  span.log({ event: 'error', message: error.message });
  throw error;
} finally {
  span.finish();
}

Spans & Traces

A trace represents the entire journey of a request through your system. Each trace consists of multiple spans, where each span represents a single operation.

Key Concepts:
  • Trace: The complete path of a request
  • Span: A single operation within a trace
  • Parent-Child: Spans can have parent-child relationships
  • Tags: Key-value metadata attached to spans

Context Propagation

Tracely automatically propagates trace context across service boundaries using W3C Trace Context standard.

// Context is automatically injected into HTTP headers
const response = await fetch('https://api.example.com/data', {
  headers: tracely.getTraceHeaders()
});

OpenTelemetry Integration

Tracely is fully compatible with OpenTelemetry, allowing you to use existing instrumentation libraries.

import { TracelyExporter } from '@tracely/opentelemetry';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new BatchSpanProcessor(
    new TracelyExporter({
      apiKey: process.env.TRACELY_API_KEY
    })
  )
);
provider.register();

MCP Protocol Support

Tracely natively supports the Model Context Protocol (MCP), enabling seamless tracing of AI agent interactions.

// Automatic MCP tool tracing
tracely.enableMCP({
  captureInputs: true,
  captureOutputs: true,
  maskSensitiveData: true
});

RAG System Tracing

Deep observability for Retrieval-Augmented Generation systems.

// Trace RAG pipeline
const ragSpan = tracely.startSpan('rag-query');

// Track query transformation
const transformSpan = tracely.startSpan('transform-query', { parent: ragSpan });
const transformedQuery = await transformQuery(userQuery);
transformSpan.finish();

// Track embedding
const embedSpan = tracely.startSpan('embed-query', { parent: ragSpan });
const embedding = await embedQuery(transformedQuery);
embedSpan.setTag('embedding.model', 'text-embedding-3-large');
embedSpan.finish();

// Track retrieval
const retrieveSpan = tracely.startSpan('retrieve-docs', { parent: ragSpan });
const docs = await vectorDB.search(embedding, { topK: 5 });
retrieveSpan.setTag('docs.count', docs.length);
retrieveSpan.setTag('docs.scores', docs.map(d => d.score));
retrieveSpan.finish();

ragSpan.finish();

REST API

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Submit Spans

POST https://api.tracely.cc/v1/spans
Content-Type: application/json

{
  "spans": [
    {
      "traceId": "abc123",
      "spanId": "span456",
      "name": "http.request",
      "timestamp": 1234567890,
      "duration": 150,
      "tags": {
        "http.method": "GET",
        "http.url": "/api/users"
      }
    }
  ]
}

Query Traces

GET https://api.tracely.cc/v1/traces?service=my-service&start=2026-01-01

SDK Methods

Core Methods

tracely.startSpan(name, options)

Creates and starts a new span.

  • name (string): The operation name
  • options (object): Optional configuration
    • parent: Parent span
    • tags: Initial tags

span.setTag(key, value)

Adds metadata to a span.

span.log(data)

Adds a log event to a span.

span.finish()

Completes the span and sends it to Tracely.