version: "1.0.1" name: everr-setup-telemetry description: Use when a task mentions adding or fixing telemetry, OpenTelemetry, local collector setup, debug telemetry, missing or stale spans/logs/metrics, or instrumentation verification.

Startup Access

Before using the everr CLI, request for the smallest sandbox access that lets Everr commands work:

• Filesystem read: ~/Library/Application Support/everr/session.json, ~/Library/Application Support/everr/session-dev.json, and their parent directory.
• Local network: 127.0.0.1, localhost, and the ports 54318, 54320, 54418, 54420.
• Production network: https://app.everr.dev

If the current tool cannot ask for a blanket permission grant, request scoped command approvals before the first Everr command instead of trying a sandboxed command that is expected to fail.

Setup Telemetry With Everr

Use this skill when an app, service, test, script, or command needs to emit telemetry into Everr. For alerting rules on that telemetry (and dashboards or runbooks), use the everr-setup-resources skill.

Local telemetry lets development match production behavior closely, and debug telemetry lets the agent collect extra evidence locally without guessing from the code.

Rule Loading

Always read the relevant rule files before editing instrumentation. Use the table below to load the minimum guidance for the code path being changed.

For most runtime work, read resolve-values, resources, sensitive-data, validation, and the signal/runtime rules that match the task.

Default Workflow

Telemetry Setup

1. Run everr local status.
2. If the collector is stopped, run everr local start or ask the user to open Everr Desktop.
3. Use the otlp: URL from everr local status in local exporters. Do not guess or mention a default localhost port unless status returned it.
4. Inspect the app before adding packages: framework, runtime, existing OTel setup, startup path, logger, test runner, deployment manifests, and existing environment variables.
5. Resolve service.name, service.version, deployment.environment.name, OTLP endpoint, and auth configuration using rules/resolve-values.md.
6. Add the smallest standard OTel setup for the stack: stable service identity, useful resource attributes, traces, logs, metrics when supported, automatic error capture, safe redaction, and an OTLP/HTTP exporter.
7. Configure endpoint selection for both environments: local development exports to the otlp: URL from everr local status; production exports to https://ingest.everr.dev/ with an ingest key from the secret manager.
8. Gate local-only exporters so local collector URLs do not ship in production bundles, and gate hosted ingest so it only runs when a production ingest key is present.
9. Trigger the instrumented path and verify fresh local rows with everr local query, filtered by the expected ServiceName, a recent time window, and a unique run, request, or test id when practical.
10. Run the project's production build (or its typecheck when no build exists). Dev servers skip strict type checking, so telemetry that flows in dev can still break the build.
11. Do not claim setup works until query results prove the new telemetry came from the path just exercised and the build passes.

Command Choice

In plans and example commands, keep the endpoint as <otlp-url-from-status> until you have actual status output.

everr local query accepts ClickHouse-style SQL against the local telemetry store.

Runtime Instrumentation

OpenTelemetry clients can export directly to the local collector. No wrapper is needed for instrumented apps.

When OpenTelemetry is missing:

• Add the SDK, OTLP/HTTP exporter, and a clear service.name.
• Check for official or community auto-instrumentation that matches the runtime and libraries before writing custom instrumentation.
• Load instrumentation before importing HTTP, database, queue, or framework modules.
• Add spans around entry points and I/O boundaries when auto-instrumentation is not enough.
• Capture errors as structured telemetry, not only terminal output.
• Redact secrets, tokens, emails, request bodies, auth headers, cookies, and raw customer payloads before export.
• Prefer instrumenting the app's existing structured logger or adding targeted OTel logs at important boundaries. Do not monkey-patch console.* or mirror all console output into telemetry unless it is temporary, development-gated, redacted, and bounded to the specific path being verified.

Do not make high-volume runtime traces or debug logs print to stdout/stderr just so they can be inspected. Export them to Everr and query them.

Server Function Convention

Instrument each framework server function invocation (TanStack Start server functions, Next.js server actions, and similar) as one span:

• Span name: serverFn {name}, falling back to serverFn when the framework provides no name.
• everr.server_function.name: the framework's own identifier for the function, verbatim (for example getActiveOrganization). Do not rename, prefix, or namespace it.
• everr.server_function.transport: http when the invocation arrived as its own request, in-process otherwise.

Debug Telemetry

Use debug telemetry when normal telemetry does not explain local behavior yet.

• Emit it at debug level or behind a development flag.
• Include concrete attributes: route, command, job id, test name, feature, user-safe identifiers, branch, commit, and correlation ids when available.
• Prefer one useful log or span at each boundary over many noisy messages inside loops.
• Remove or gate anything that should not be present in production.

Do not optimize local debug telemetry for storage cost. Rich local evidence is usually cheaper than another round of guessing.

Build, Lint, And Test Commands

Use everr wrap -- <command> only when the command is not OpenTelemetry-instrumented and the task needs its output in local telemetry.

• The wrapped command runs only when the local collector is available.
• stdout and stderr lines are mirrored into logs.
• The service name is everr-wrap-<cmd>.
• The wrapped command keeps its original exit code.

For Playwright or other E2E tests, capture both the app under test and the test runner's view of browser failures. Add a run id such as e2e.run_id=<uuid> to resource attributes, emit page errors, console errors, and request failures as OTel logs, then query by that run id.

Production Export

When setting up production telemetry, wire the app to Everr's hosted OTLP HTTP ingest endpoint and require an organization ingest key from the user's secret manager.

Use these production defaults:

• Endpoint: https://ingest.everr.dev/
• Header: Authorization: Bearer <ingest-key>
• Secret environment variable: EVERR_INGEST_KEY
• Service identity: a stable service.name hardcoded in the setup module for each service

If no production ingest key exists yet, tell the user to create one in the Everr dashboard from the user menu's API keys page, then store it in the deployment secret manager. Do not invent credentials, print keys, hardcode keys, or commit keys.

Implementation expectations:

• Use the local collector endpoint for development and test runs.
• Use hosted ingest only when EVERR_INGEST_KEY is set.
• Keep production telemetry lower-noise than local debug telemetry.
• Keep secrets, tokens, emails, request bodies, and raw customer payloads out of attributes and log bodies.
• Do not expose EVERR_INGEST_KEY in browser bundles. Browser production telemetry authenticates with a public origin-bound ingest key instead; see rules/browser.md.
• Preserve normal crash and shutdown behavior while flushing telemetry.

Validation

Do not claim telemetry works until you have exercised the instrumented path and queried fresh telemetry that proves it.

See rules/validation.md for the full validation checklist.

Common Mistakes