agent-telemetry_skill

Overview

This skill makes application runtime behavior queryable by coding agents by adding structured logs and telemetry endpoints. It helps teams add JSON-based logging, expose logs to agents via files, dev endpoints, or CLI tools, and document how agents should query them. Use it to make debugging and observability agent-friendly without granting console or SSH access.

How this skill works

I audit the codebase for existing logging and telemetry endpoints, classify gaps, and implement a minimal structured logging setup if missing. I then expose recent log entries to agents through one or more access mechanisms (log file, development-only HTTP endpoint, or a CLI query script) and add precise documentation and example commands for agent consumption. Finally, I validate the loop by triggering requests and confirming agents can find relevant entries quickly.

When to use it

• When asked to "add telemetry", "make logs accessible to agents", or "add observability".
• When debugging is difficult because logs are unstructured or unavailable.
• When agent docs lack instructions for querying application logs.
• When setting up logging for a new or existing web application.
• When agents must understand runtime behavior but cannot access dashboards or consoles.

Best practices

• Write structured JSON logs with consistent fields: timestamp, level, message, requestId, userId, path, statusCode, duration.
• Log at boundaries: request middleware, error handlers, external calls, and key business transitions.
• Include correlation IDs for request tracing and avoid logging sensitive data; redact PII and tokens.
• Provide at least one agent-friendly access method: local log file, dev-only /__dev/logs endpoint, or a scripts/query-logs.sh tool.
• Document copy-pasteable query commands in agent docs and limit dev endpoint responses (default max 100 entries).

Example use cases

• Add a request-logging middleware to capture {timestamp, level, requestId, method, path, statusCode, duration} for a new Express app.
• Create a development-only GET /__dev/logs endpoint that filters by level, path, or requestId for a Next.js project.
• Provide a scripts/query-logs.sh wrapper in a monorepo so agents can query logs across multiple services.
• Write structured logs to a mounted file path in Docker and give agents commands to tail and jq-filter errors.
• Update agent docs with exact commands to find errors, trace requests by requestId, and filter logs by time range.