Span conventions
Ivy stores standard OpenTelemetry spans. This is a summary of the attributes its Lambda layer emits and the ones Ivy reads, so you can send compatible spans from any OpenTelemetry SDK. The full reference is in the repository.
Resource
| Attribute | Example |
|---|---|
service.name, faas.name |
checkout-api-prod-createOrder |
cloud.provider, cloud.platform |
aws, aws_lambda |
cloud.region, cloud.account.id |
eu-west-1, 123456789012 |
faas.version, faas.max_memory |
$LATEST, memory in bytes |
Invocation (root span)
One per invocation; Ivy's invocation list, error groups and billing are built from it.
| Attribute | |
|---|---|
ivy.invocation = true |
Required marker |
faas.invocation_id |
AWS request ID |
faas.coldstart, ivy.init_duration_ms |
Cold start and init duration |
faas.trigger, ivy.trigger.source |
http, pubsub, …; aws:apigateway, aws:sqs, aws:eventbridge, … |
cloud.resource_id |
Function ARN |
http.request.method, url.path, http.route, http.response.status_code |
HTTP triggers |
ivy.payload.request, ivy.payload.response |
Event and result, JSON, capped |
ivy.billed_duration_ms, ivy.memory_max_used_mb |
From the Lambda platform report |
Errors set span status ERROR, error.type, and an exception event with type, message and stack trace.
Failures outside the handler
Set by the extension from the Lambda Telemetry API:
| Attribute | |
|---|---|
error.type |
Runtime.ImportModuleError, Runtime.OutOfMemory, Runtime.ExitError, Sandbox.Timedout, … |
ivy.failure.phase |
init or invoke |
ivy.platform.status |
failure, error or timeout |
ivy.synthetic = true |
The extension created the span because the tracer couldn't |
The last log lines (up to 50 lines or 8 KB, redacted) are attached as log events.
Outgoing calls
AWS SDK: span name DynamoDB.GetItem; rpc.system = aws-api, rpc.service, rpc.method, aws.request_id, cloud.region, plus aws.dynamodb.table_names, aws.s3.bucket and aws.s3.key, messaging.system and messaging.destination.name (SQS, SNS), faas.invoked_name (Lambda), aws.eventbridge.bus.
HTTP: span name POST api.stripe.com; http.request.method, url.full (query string redacted), server.address, http.response.status_code, and ivy.http.request.headers and ivy.http.response.headers with sensitive headers redacted.
Both carry ivy.payload.request and ivy.payload.response.
Logs
console.* calls become log events on the invocation span, with log.severity and log.message (capped at 4 KB).
LLM spans
Spans that libraries create through @opentelemetry/api keep their own names and attributes. Ivy reads three families: the Vercel AI SDK's ai.* attributes, OpenTelemetry GenAI gen_ai.*, and their variants, to show messages, tool calls, tokens and time to first token. See LLM observability.
Redaction
- Each
ivy.payload.*value is capped atIVY_MAX_PAYLOAD_BYTES(16 KB). Truncated values end with…[truncated N bytes]and the span getsivy.payload.truncated = true. - Keys matching
IVY_REDACT_KEYSare replaced with"[redacted]"at any depth before anything leaves the function. The default list:password, secret, token, authorization, cookie, apikey, api_key, accesskey, secretaccesskey, sessiontoken, creditcard, cardnumber, cvv.
Full reference: span-conventions.md.