القائمة
createStructuredError, parseError, recordStructuredError. API errors with message, why, fix, link; client parsing for UI. Use in API routes and client catch blocks.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use this skill when instrumenting AI/LLM/agent code with OpenTelemetry GenAI semantic conventions — traceGenAI() spans, token usage and cost, gen_ai.* attributes, GenAI metric views, content/evaluation events, the Vercel AI SDK bridge, or the agent identity/delegation/policy/audit governance layer. This is the canonical home for everything GenAI in autotel (the core `autotel` package is AI-free).
Review TypeScript/JavaScript code for OpenTelemetry instrumentation patterns and guide adoption of autotel. Covers Next.js, Nuxt, Nitro, TanStack Start, SvelteKit, NestJS, Express, Hono, Fastify, Elysia, Cloudflare Workers, AWS Lambda, edge runtimes, and standalone Node. Detects unstructured tracing, missing span attributes, manual exporter setup, broken context propagation, exposed PII, and ad-hoc error handling. Covers spans, metrics, logs, structured errors, the autotel processor pipeline (tail-sampling, attribute redaction, span-name normalisation, filtering, baggage), built-in enrichers (user agent, geo, request size) and custom `defineEnricher`, `defineWorkerFetch` for Cloudflare async drains, multi-vendor OTLP backends (Honeycomb, Datadog, Grafana Cloud, Sentry, Axiom, HyperDX), `composeSpanProcessors` / `composeSubscribers` / `composePostProcessors` for pipelines, AI SDK observability with gen-ai semantic conventions, and end-to-end OTLP testing.
Query OpenTelemetry telemetry (traces, metrics, logs, LLM analytics) via the autotel CLI. Use when the user asks about a production issue, slow request, error spike, expensive LLM call, or any "what is happening in my service" question. Each command returns one JSON document on stdout — parse it and answer from the data.
OpenTelemetry instrumentation for MCP (Model Context Protocol). instrumentMCPServer, instrumentMCPClient; W3C trace context via _meta; tools, resources, prompts. Security observability: annotation hints, payload-size & char-budget signals, pluggable prompt-injection classifier, spotlighting.
When to use trace vs span vs request logger vs events in Autotel. Init once at startup, package exports (autotel, autotel/event, autotel/testing). Use for setup and choosing the right API.
trace(), span(), instrument(), init(). Factory vs direct pattern, name inference. Sync init; use node-require for optional deps. Load when wrapping handlers or functions with spans.
| name | autotel-structured-errors |
| description | createStructuredError, parseError, recordStructuredError. API errors with message, why, fix, link; client parsing for UI. Use in API routes and client catch blocks. |
Throw errors with createStructuredError({ message, why?, fix?, link?, status?, cause? }) in API routes and services. On the client, use parseError(caught) to get message, status, why, fix, link for toasts and UI.
Server (API route or service):
import { createStructuredError } from 'autotel';
if (!user) {
throw createStructuredError({
message: 'User not found',
status: 404,
why: `No user with ID "${userId}"`,
fix: 'Check the user ID and try again',
link: 'https://docs.example.com/errors/user-not-found',
});
}
Client:
import { parseError } from 'autotel';
try {
await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(data) });
} catch (err) {
const e = parseError(err);
toast.error(e.message, { description: e.why });
if (e.fix) setHelp(e.fix);
if (e.link) setDocLink(e.link);
}
Wrap a caught error (preserve cause):
try {
await stripe.charges.create(data);
} catch (err) {
throw createStructuredError({
message: 'Payment failed',
status: 402,
why: err instanceof Error ? err.message : 'Unknown error',
fix: 'Try a different payment method or contact support',
link: 'https://docs.stripe.com/declines',
cause: err,
});
}
Record on current span: Use recordStructuredError(ctx, error) or the request logger's .error(error, fields) so the span gets error attributes and status.
For new exception event flows, prefer request-logger/log-based correlation and keep span-event compatibility as an implementation detail (processors/export path), not a new app-level dependency.
parseError handles FetchError (ofetch), nested data.data, and plain Error. Returns { message, status, why?, fix?, link?, raw }.
Wrong:
throw new Error('Payment failed');
Correct:
throw createStructuredError({
message: 'Payment failed',
status: 402,
why: 'Card declined by issuer',
fix: 'Try a different payment method',
link: 'https://docs.example.com/payments',
});
Clients and agents need structured fields (why, fix, link) for actionable errors. parseError() reads these from API responses.
Source: docs/AGENT-GUIDE.md, AGENTS.md
Wrong:
catch (err) {
toast.error(err.message);
}
Correct:
import { parseError } from 'autotel';
catch (err) {
const e = parseError(err);
toast.error(e.message, { description: e.why });
if (e.fix) showFix(e.fix);
if (e.link) setDocLink(e.link);
}
parseError() extracts status, why, fix, and link from API error responses and FetchError so the UI can show them.
Source: docs/AGENT-GUIDE.md
Targets autotel v2.23.x.
See also: autotel-request-logging/SKILL.md — use .error() to record errors in the request snapshot.