# 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](https://ivytrace.dev/features/llm-observability).

## Redaction

- Each `ivy.payload.*` value is capped at `IVY_MAX_PAYLOAD_BYTES` (16 KB). Truncated values end with `…[truncated N bytes]` and the span gets `ivy.payload.truncated = true`.
- Keys matching `IVY_REDACT_KEYS` are 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](https://github.com/ivytrace/ivy/blob/main/docs/implementation/span-conventions.md).

---

Source: https://ivytrace.dev/docs/span-conventions · Updated 2026-11-14