Getting Started with Observability

This guide will help you get started with observability in ADK-TS. You'll learn how to initialize the telemetry service and start collecting traces and metrics. The initialization patterns shown here work for both local development and production environments. For production-specific considerations like privacy controls, performance tuning, and security, see the Production Configuration guide.

Installation

Telemetry dependencies are already included in @iqai/adk. No additional installation is required.

The following OpenTelemetry packages are included:

{
  "@opentelemetry/api": "^1.9.0",
  "@opentelemetry/sdk-metrics": "^2.2.0",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
  "@opentelemetry/exporter-trace-otlp-http": "^0.208.0"
}

Basic Initialization

Initialize the telemetry service before any agent operations:

import { telemetryService } from '@iqai/adk';

await telemetryService.initialize({
  appName: 'my-agent-app',
  appVersion: '1.0.0',
  otlpEndpoint: 'http://localhost:4318/v1/traces',
  enableMetrics: true,
  enableTracing: true,
});

import { telemetryService } from '@iqai/adk';

await telemetryService.initialize({
  // Required
  appName: 'my-agent-app',
  otlpEndpoint: 'http://localhost:4318/v1/traces',

  // Optional
  appVersion: '1.0.0',
  environment: 'development',

  // Feature flags
  enableTracing: true,
  enableMetrics: true,
  // Auto-instrumentation automatically traces HTTP, database, and other operations
  enableAutoInstrumentation: true, // Set false to disable automatic instrumentation

  // Privacy controls
  captureMessageContent: true, // Set false for production

  // Performance tuning
  samplingRatio: 1.0, // 1.0 = 100% sampling
  metricExportIntervalMs: 60000, // 1 minute

  // Custom resource attributes
  resourceAttributes: {
    'deployment.name': 'local',
    'team': 'platform',
  },
});

import { telemetryService } from '@iqai/adk';

// The telemetry system respects standard OpenTelemetry environment variables
// OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES, NODE_ENV, etc.

await telemetryService.initialize({
  appName: process.env.OTEL_SERVICE_NAME || 'my-agent-app',
  otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
  environment: process.env.NODE_ENV || 'development',
});

# Set environment variables
export OTEL_SERVICE_NAME=my-agent-app
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development,team=platform
export NODE_ENV=development
export ADK_CAPTURE_MESSAGE_CONTENT=true

Local Development Setup

Running with Jaeger

Jaeger is a popular open-source distributed tracing system. Use it for local development:

# Start Jaeger all-in-one (includes OTLP receiver)
docker run -d \
  --name jaeger \
  -p 4318:4318 \
  -p 16686:16686 \
  jaegertracing/all-in-one:latest

Your ADK app will send traces to http://localhost:4318/v1/traces, and you can view them at http://localhost:16686.

Running with OpenTelemetry Collector

For more advanced setups that need to route telemetry to multiple backends or apply processing, use the OpenTelemetry Collector:

1. Create collector configuration (otel-collector-config.yaml):

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  logging:
    loglevel: debug
  otlp/jaeger:
    endpoint: http://localhost:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [logging, otlp/jaeger]
    metrics:
      receivers: [otlp]
      exporters: [logging]

2. Run the collector:

docker run -d \
  -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
  -p 4318:4318 \
  otel/opentelemetry-collector:latest \
  --config=/etc/otel-collector-config.yaml

Complete Example

Here's a complete example that initializes telemetry and runs an agent:

import { telemetryService, AgentBuilder } from "@iqai/adk";

async function main() {
  // Initialize telemetry first
  await telemetryService.initialize({
    appName: "example-agent",
    appVersion: "1.0.0",
    otlpEndpoint: "http://localhost:4318/v1/traces",
    enableMetrics: true,
    enableTracing: true,
  });

  // Build and run agent
  const agent = AgentBuilder.withModel("gemini-2.5-flash").build();

  const response = await agent.ask("What is the capital of France?");
  console.log(response);

  // Graceful shutdown
  process.on("SIGTERM", async () => {
    await telemetryService.shutdown(5000);
    process.exit(0);
  });

  process.on("SIGINT", async () => {
    await telemetryService.shutdown(5000);
    process.exit(0);
  });
}

main().catch(console.error);

Viewing Traces

Once your application is running and sending traces:

1. Open Jaeger UI: Navigate to http://localhost:16686
2. Select Service: Choose your service name (e.g., example-agent)
3. Find Traces: Click "Find Traces" to see all traces
4. Explore: Click on any trace to see the detailed execution flow

You'll see:

• Agent invocation spans
• Tool execution spans
• LLM call spans with token usage
• Auto-instrumented HTTP calls

Configuration Options

Required Options

• appName - Service name for identification in traces
• otlpEndpoint - OTLP HTTP endpoint URL for sending traces

Optional Options

• appVersion - Application version
• environment - Deployment environment (development, staging, production)
• enableTracing - Enable distributed tracing (default: true)
• enableMetrics - Enable metrics collection (default: true)
• enableAutoInstrumentation - Enable automatic instrumentation for HTTP, databases, and file system operations (default: true). Set to false if you only want ADK-specific traces.
• captureMessageContent - Capture LLM prompts/completions (default: true)
• samplingRatio - Trace sampling ratio 0.0-1.0 (default: 1.0)
• metricExportIntervalMs - Metrics export interval in milliseconds (default: 60000)
• otlpHeaders - Custom headers for OTLP requests
• resourceAttributes - Custom resource attributes

Next Steps