Stable event contracts
The agent is guided toward named events, bounded snake_case fields, explicit units, and identifiers that remain useful in SQL.
Put the skill to work
Instrument one real agent workflow today
Start with a ready API key and agent prompt, run one representative workflow, and verify the resulting event before building a dashboard.
What the skill covers
Instructions that end in inspectable data
Safe collection boundaries
Raw prompts, completions, credentials, authorization headers, and private payloads stay out of the analytics path by default.
An end-to-end result
Instrumentation is not finished until representative events arrive and a query or dashboard proves the workflow is visible.
Telemetry wrapper examples
Give the agent a small, reviewable ingestion boundary
Pass the API key from trusted server-side configuration and verify a real event with SQL. Anonymous keys support this workflow; claim the workspace before creating dashboards. Keep the Python User-Agent header so requests reach the API.
typescript
TypeScript telemetry wrapper
javascript
type TelemetryEvent = Record<string, unknown>;
export async function emitTelemetry(
apiKey: string,
table: string,
data: TelemetryEvent,
) {
const response = await fetch("https://api.telemetry.sh/log", {
method: "POST",
headers: {
Authorization: apiKey,
"Content-Type": "application/json",
},
body: JSON.stringify({ table, data }),
});
if (!response.ok) {
throw new Error(`Telemetry ingestion failed: ${response.status}`);
}
}python
Python telemetry wrapper
python
import json
from urllib.request import Request, urlopen
def emit_telemetry(api_key: str, table: str, data: dict) -> int:
request = Request(
"https://api.telemetry.sh/log",
data=json.dumps({"table": table, "data": data}).encode(),
headers={
"Authorization": api_key,
"Content-Type": "application/json",
"User-Agent": "telemetry-agent/1.0",
},
method="POST",
)
with urlopen(request, timeout=5) as response:
return response.statusStart here
Paste one bounded brief
Replace the placeholder with a server-side API key, then ask the agent to inspect the repository before choosing event boundaries.
agent prompt
AI agent observability prompt
text
Instrument this project with structured logs using /skill.md.
Use this Telemetry API key: YOUR_API_KEY
Anonymous keys: logging and synchronous SQL work without signup. Claim the existing workspace at https://telemetry.sh/register with the same key before creating dashboards or alerts. If it is unclaimed, finish with verified event readback and mark account features as pending signup.
Please:
1. Find the most important user-facing flows, background jobs, and AI/tooling workflows.
2. Add structured logging with pragmatic snake_case tables and fields.
3. Capture the key signals for each workflow, including status, latency, identifiers, and error context when relevant.
4. Run one real user-facing or operational flow through the instrumented application and verify its event appears in Telemetry. Do not use telemetry_quickstart for this milestone.
5. Run a read-only query over that real event, then create a high-level dashboard with charts and tables that summarize the most important signals in this project.
6. Tell me what you instrumented, which real flow you verified, which tables you created, and which dashboard views I should review first.
Prefer small, composable events over giant payloads, and optimize for dashboards that humans can scan quickly.Review boundary
Keep a human in control of the contract
The skill helps an agent find useful workflow boundaries, but your team still owns the event meaning, allowed fields, retention policy, and operational thresholds.
- Review every new table and field before deployment.
- Use bounded identifiers instead of private payloads.
- Verify success, failure, and terminal outcomes.
Continue the workflow
AI agent telemetry dashboard template
Start with a bounded event schema and a reviewable dashboard for runs, tools, latency, cost, failures, and outcomes.
Open guideAI agent monitoring
Choose useful run, tool, model, cost, failure, and outcome boundaries.
Open guideAgent prompt pack
Copy focused briefs for product analytics, OpenAI costs, APIs, revenue, and jobs.
Open guideStructured logging guide
Review event design, privacy boundaries, delivery behavior, and verification.
Open guideClaude Code observability
Apply the reviewed event contract and verification loop from a Claude Code implementation pass.
Open guideCursor telemetry setup
Use a focused Cursor workflow for activation, retention, and inspectable dashboard instrumentation.
Open guideCodex instrumentation prompt
Give Codex a bounded brief for product, reliability, and outcome telemetry with verification.
Open guideOpenAI cost tracking guide
Connect model, token, latency, retry, and accepted-outcome events to a reviewable SQL cost dashboard.
Open guideInstrument the first workflow, then inspect the result
Start free with a provisioned workspace, API key, agent prompt, and starter dashboard. Connect one real workflow, verify the event, and save the first useful query.