Agent-Skills.md

Agent Skills: OpenTelemetry Instrumentation with Kopai

Instrument applications with OpenTelemetry SDK and validate telemetry using Kopai. Use when setting up observability, adding tracing/logging/metrics, testing instrumentation, debugging missing telemetry data, or when traces/logs/metrics aren't appearing after setup. Also use when users say things like "my traces aren't showing up", "I don't see any data", or "how do I add observability to my app".

UncategorizedID: kopai-app/kopai-mono/otel-instrumentation

Repository

kopai-app/kopai-mono
kopai-appLicense: Apache-2.0
91

Install this agent skill to your local

pnpm dlx add-skill https://github.com/kopai-app/kopai-mono/tree/HEAD/skills/otel-instrumentation

Skill Files

Browse the full folder contents for otel-instrumentation.

Download Skill

Loading file tree…

skills/otel-instrumentation/SKILL.md

Skill Metadata

Name
otel-instrumentation
Description
Instrument applications with OpenTelemetry SDK and validate telemetry using Kopai. Use when setting up observability, adding tracing/logging/metrics, testing instrumentation, debugging missing telemetry data, or when traces/logs/metrics aren't appearing after setup. Also use when users say things like "my traces aren't showing up", "I don't see any data", or "how do I add observability to my app".

OpenTelemetry Instrumentation with Kopai

Guide for instrumenting applications with OpenTelemetry SDK and validating telemetry locally using Kopai.

Quick Reference

# Start backend
npx @kopai/app start

# Configure app
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=my-service

# Validate telemetry
npx @kopai/cli traces search --service my-service --json
npx @kopai/cli logs search --service my-service --json
npx @kopai/cli metrics discover --json

Workflow

  1. Start backend — npx @kopai/app start
  2. Set env vars — OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 and OTEL_SERVICE_NAME=<name>
  3. Instrument app — install SDK + auto-instrumentation for your language (see rules below)
  4. Validate — npx @kopai/cli traces search --service <name> --json. If empty: check endpoint/port, verify app is running and generating traffic, wait 10-30s and retry
  5. Troubleshoot — if still no data, check rules in section 4 below

Quick Example (Node.js)

npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/api

Create instrumentation.mjs:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
const sdk = new NodeSDK({ instrumentations: [getNodeAutoInstrumentations()] });
sdk.start();

Run: node --import ./instrumentation.mjs server.mjs

Rules

1. Setup (CRITICAL)

  • setup-backend - Start Kopai Backend
  • setup-environment - Configure Environment

2. Language SDKs (HIGH)

  • lang-nodejs - Node.js Instrumentation
  • lang-nextjs - Next.js Instrumentation
  • lang-python - Python Instrumentation
  • lang-go - Go Instrumentation
  • lang-java - Java Instrumentation
  • lang-dotnet - .NET Instrumentation
  • lang-ruby - Ruby Instrumentation
  • lang-php - PHP Instrumentation
  • lang-rust - Rust Instrumentation
  • lang-erlang - Erlang/Elixir Instrumentation
  • lang-cpp - C++ Instrumentation

3. Validation (HIGH)

  • validate-traces - Validate Traces
  • validate-logs - Validate Logs
  • validate-metrics - Validate Metrics

4. Troubleshooting (MEDIUM)

  • troubleshoot-no-data - No Data Received
  • troubleshoot-missing-spans - Missing Spans
  • troubleshoot-missing-attrs - Missing Attributes
  • troubleshoot-wrong-port - Wrong Port

Read rules/<rule-name>.md for details.

References