Metrics

ADK-TS collects metrics for agent performance, tool usage, LLM interactions, and error rates. All metrics follow OpenTelemetry standards and are exported via OTLP.

Available Metrics

The telemetry system automatically collects metrics for all agent operations. Metrics are exported at regular intervals (configurable via metricExportIntervalMs). Metrics can be monitored using counters and histograms.

Counters

Counters track the total number of operations:

Histograms

Histograms track distributions of values:

Metric Labels

All metrics include labels for filtering and aggregation:

• agent.name - Name of the agent
• tool.name - Name of the tool (for tool metrics)
• model - LLM model name (for LLM metrics)
• environment - Deployment environment
• status - Operation status (success, error)
• error_type - Type of error (for error metrics)
• context - Error context (for error metrics)

Metric Dimensions

When recording metrics, you can include additional dimensions:

telemetryService.recordAgentInvocation({
  agentName: "my-agent",
  environment: "production",
  status: "success",
  // Additional dimensions can be added via resource attributes
});

Resource attributes are automatically included as metric labels, allowing you to filter and aggregate by deployment, team, or any custom attribute.

Recording Custom Metrics

You can manually record metrics for custom operations:

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

// Record agent invocation
telemetryService.recordAgentInvocation({
  agentName: "my-agent",
  environment: "production",
  status: "success",
});

// Record agent duration
telemetryService.recordAgentDuration(1500, {
  agentName: "my-agent",
  environment: "production",
  status: "success",
});

// Record tool execution
telemetryService.recordToolExecution({
  toolName: "search_web",
  agentName: "my-agent",
  environment: "production",
  status: "success",
});

// Record LLM tokens
telemetryService.recordLlmTokens(150, 75, {
  model: "gpt-4",
  agentName: "my-agent",
  environment: "production",
  status: "success",
});

Metric Export

Metrics are automatically exported to your configured OTLP endpoint at regular intervals. The default export interval is 60 seconds (60000ms), but you can configure it:

await telemetryService.initialize({
  appName: "my-app",
  otlpEndpoint: "http://localhost:4318/v1/traces",
  metricExportIntervalMs: 30000, // Export every 30 seconds
});

Viewing Metrics

ADK-TS sends metrics via OTLP to any compatible observability backend. You'll need to set up an external metrics visualization tool separately. Popular options include Grafana (with Tempo or Prometheus), Datadog, New Relic, and Honeycomb.

Grafana

Grafana is a popular open-source visualization tool that can display metrics from various backends:

1. Set up Grafana: See the Platform Integrations guide for Docker setup instructions
2. Configure OTLP receiver in your observability backend
3. Create dashboards with queries for ADK-TS metrics
4. Set up alerts based on metric thresholds

Example Grafana queries:

• rate(adk_agent_invocations_total[5m]) - Agent invocation rate
• histogram_quantile(0.95, adk_llm_duration_bucket) - 95th percentile LLM latency
• sum(rate(adk_errors_total[5m])) - Error rate

Prometheus

Prometheus is a metrics database that can be used with Grafana for visualization. If using Prometheus, configure the OpenTelemetry Collector to export metrics in Prometheus format:

# otel-collector-config.yaml
exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]

Common Use Cases

Related Topics