opensearch-project/agent-health/setup-collector

Claude Code and agent skill by opensearch-project/agent-health

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install opensearch-project/agent-health/setup-collector

SKILL.md

Set Up Trace Collection Pipeline

You are helping the user configure a pipeline to get their agent's OTel traces into OpenSearch where Agent Health can read them.

Architecture Options

Agent → OTLP/HTTP → [Pipeline] → OpenSearch

Three pipeline options:

OptionBest ForComplexity
OSIS (OpenSearch Ingestion)AWS-managed, productionLow (managed)
OTel CollectorSelf-hosted, flexible routingMedium
Direct exportDev/testing onlyLowest

Option 1: OSIS Pipeline (Recommended for AWS)

Prerequisites
  • AWS account with OSIS access
  • OpenSearch domain (managed or serverless)
Pipeline Configuration
yaml
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"
Agent Configuration
bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-osis-pipeline.us-west-2.osis.amazonaws.com/v1/traces
OTEL_SERVICE_NAME=my-agent

Option 2: OTel Collector (Self-hosted)

docker-compose.yml
yaml
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports:
      - "4318:4318"  # OTLP HTTP
    volumes:
      - ./otel-config.yaml:/etc/otelcol-contrib/config.yaml
otel-config.yaml
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]
Agent Configuration
bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
OTEL_SERVICE_NAME=my-agent

Option 3: Direct Export (Dev Only)

Export directly to OpenSearch Data Prepper format. Not recommended for production (no batching, no retry).

bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-opensearch:9200/_plugins/_trace_analytics/v1/traces

Agent Health Configuration

Once traces are flowing to OpenSearch, configure Agent Health to read them:

bash
# 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

Verification Checklist

  1. Agent sends spans: Check agent logs for "telemetry enabled" message
  2. Pipeline receives: Check OSIS/Collector metrics for incoming spans
  3. OpenSearch has data: Query otel-v1-apm-span-* index
  4. Agent Health sees traces: Open Traces tab, verify spans appear with correct categorization

Troubleshooting

IssueCheck
No spans arrivingIs OTEL_EXPORTER_OTLP_ENDPOINT correct? Is the agent calling provider.register()?
Spans in OS but not in Agent HealthCheck index pattern matches what Agent Health queries (otel-v1-apm-span-*)
Auth errorsCheck IAM role for OSIS, or username/password for basic auth
Spans arrive but incompleteEnsure provider.shutdown() is called on agent exit (flushes batch)

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
35
Repository forks
28
7-day trend score
0

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/opensearch-project/agent-health/setup-collector/badge)](https://verified-skill.com/skills/opensearch-project/agent-health/setup-collector)

Something wrong with this skill or its page? Tell us.