// Set up an OpenTelemetry collector or OSIS pipeline to route traces from an agent to OpenSearch for Agent Health consumption. Covers OSIS, OTel Collector, and direct export configurations.
Create a pull request for Agent Health following all compliance requirements. Use after implementing a feature or fix. Handles SPDX headers, DCO signoff, CHANGELOG, and the PR template.
Diagnose and fix bugs in Agent Health. Use when a user reports a bug, failing test, or unexpected behavior. Follows a systematic diagnosis → fix → verify workflow.
Guided feature implementation for Agent Health. Use when a user wants to add a new capability, endpoint, CLI command, or UI component to the Agent Health project. Ensures correct architecture layer, coding conventions, test coverage, and PR readiness.
Add OpenTelemetry instrumentation to an AI agent for Agent Health observability. Use when a user wants to make their agent's traces visible in Agent Health dashboards, or when debugging why traces aren't appearing. Covers span structure, Gen AI semantic conventions, required attributes, and OTLP exporter setup.
Write tests for Agent Health following project conventions. Use when adding tests for new features, bug fixes, or improving coverage. Covers Jest setup, mocking patterns, path aliases, and coverage thresholds.
Use when working on config loading, authentication, AWS profiles, or data source resolution. Explains the two config systems (TS vs JSON), auth priority, and multi-profile setup.
| name | setup-collector |
| description | Set up an OpenTelemetry collector or OSIS pipeline to route traces from an agent to OpenSearch for Agent Health consumption. Covers OSIS, OTel Collector, and direct export configurations. |
You are helping the user configure a pipeline to get their agent's OTel traces into OpenSearch where Agent Health can read them.
Agent → OTLP/HTTP → [Pipeline] → OpenSearch
Three pipeline options:
| Option | Best For | Complexity |
|---|---|---|
| OSIS (OpenSearch Ingestion) | AWS-managed, production | Low (managed) |
| OTel Collector | Self-hosted, flexible routing | Medium |
| Direct export | Dev/testing only | Lowest |
version: "2"
otel-trace-pipeline:
source:
otel_trace_source:
path: "/v1/traces"
processor:
- otel_trace_raw:
sink:
- opensearch:
hosts: ["https://your-opensearch-domain.us-west-2.es.amazonaws.com"]
index: "otel-v1-apm-span-*"
aws:
sts_role_arn: "arn:aws:iam::ACCOUNT:role/osis-role"
region: "us-west-2"
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-osis-pipeline.us-west-2.osis.amazonaws.com/v1/traces
OTEL_SERVICE_NAME=my-agent
services:
otel-collector:
image: otel/opentelemetry-collector-contrib:latest
ports:
- "4318:4318" # OTLP HTTP
volumes:
- ./otel-config.yaml:/etc/otelcol-contrib/config.yaml
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
processors:
batch:
timeout: 5s
send_batch_size: 100
exporters:
opensearch:
http:
endpoint: "https://your-opensearch:9200"
tls:
insecure: false
dataset: "traces"
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [opensearch]
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
OTEL_SERVICE_NAME=my-agent
Export directly to OpenSearch Data Prepper format. Not recommended for production (no batching, no retry).
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-opensearch:9200/_plugins/_trace_analytics/v1/traces
Once traces are flowing to OpenSearch, configure Agent Health to read them:
# In your Agent Health .env
OPENSEARCH_LOGS_ENDPOINT=https://your-opensearch:9200
OPENSEARCH_LOGS_USERNAME=admin
OPENSEARCH_LOGS_PASSWORD=admin
# Or for AWS SigV4:
# OPENSEARCH_LOGS_AUTH_TYPE=sigv4
# OPENSEARCH_LOGS_AWS_REGION=us-west-2
otel-v1-apm-span-* index| Issue | Check |
|---|---|
| No spans arriving | Is OTEL_EXPORTER_OTLP_ENDPOINT correct? Is the agent calling provider.register()? |
| Spans in OS but not in Agent Health | Check index pattern matches what Agent Health queries (otel-v1-apm-span-*) |
| Auth errors | Check IAM role for OSIS, or username/password for basic auth |
| Spans arrive but incomplete | Ensure provider.shutdown() is called on agent exit (flushes batch) |