--- title: "Span Data Conventions" url: https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions/ --- # Span Data Conventions The Span Interface specifies a series of *timed* application events that have a start and end time. Below describes the conventions for the Span interface for the `data` field on the span. The `data` field on the span is expected to follow [OpenTelemetry's semantic conventions for attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/trace.md) as much as possible. Keys on the `data` field should be lower-case and use underscores instead of camel-case. There are some exceptions to this, but these exist because of backwards compatibility. Below describes the conventions for the Span interface for the `data` field on the span that are currently used by the product or are important to bring up. ## [General](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#general) | Attribute | Type | Description | Examples | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/app/myapplication/http/handler/server.py` | | `code.lineno` | number | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function` | `42` | | `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `server_request` | | `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `http.handler` | ## [HTTP](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#http) | Attribute | Type | Description | Examples | | -------------------------------------- | ------ | ----------------------------------------------------- | ------------------ | | `http.query` | string | The Query string present in the URL. | `?foo=bar&bar=baz` | | `http.fragment` | string | The Fragments present in the URI (Browser SDKs only). | `#details` | | `http.request.method` | string | The HTTP method used. | `GET` | | `http.response.status_code` | int | The status HTTP response. | `404` | | `http.response_content_length` | number | The encoded body size of the response (in bytes). | `123` | | `http.decoded_response_content_length` | number | The decoded body size of the response (in bytes). | `456` | | `http.response_transfer_size` | number | The transfer size of the response (in bytes). | `789` | | `server.address` | string | URL domain name. | `example.com` | | `server.port` | int | URL server port number | `8080` | ## [Mobile](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#mobile) | Attribute | Type | Description | Examples | | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `blocked_main_thread` | boolean | Whether the main thread was blocked by the span. | `true` | | `call_stack` | StackFrame\[] | The most relevant stack frames, that lead to the File I/O span. The stack frame should adhere to the [`StackFrame`](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/stacktrace.md#frame-attributes) interface. | | | `url` | string | The URL of the resource that was fetched. | `https://example.com` | | `type` | string | More granular type of the operation happening. | `fetch` | | `frames.total` | int | The number of total frames rendered during the lifetime of the span. | `60` | | `frames.slow` | int | The number of slow frames rendered during the lifetime of the span. | `2` | | `frames.frozen` | int | The number of frozen frames rendered during the lifetime of the span. | `1` | | `frames.delay` | number | The sum of all delayed frame durations in seconds during the lifetime of the span. For more information see [frames delay](https://develop.sentry.dev/sdk/performance/frames-delay.md). | `1.3246` | ## [Browser](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#browser) | Attribute | Type | Description | Examples | | --------------------------------- | ------ | ------------------------------------------- | --------------------- | | `url` | string | The URL of the resource that was fetched. | `https://example.com` | | `type` | string | The type of the resource that was fetched. | `xhr` | | `resource.render_blocking_status` | string | The render blocking status of the resource. | `non-blocking` | ## [UI](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#ui) | Attribute | Type | Description | Examples | | ------------------------ | ------- | ------------------------------------------------------------------------------------ | -------- | | `ui.contributes_to_ttid` | boolean | Whether the span execution contributed to the TTID (time to initial display) metric. | `true` | | `ui.contributes_to_ttfd` | boolean | Whether the span execution contributed to the TTFD (time to fully drawn) metric. | `true` | ## [Database](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#database) | Attribute | Type | Description | Examples | | ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `db.system` | string | An identifier for the database management system (DBMS) product being used. See [OpenTelemetry docs for a list of well-known identifiers](https://opentelemetry.io/docs/specs/semconv/database/). | `postgresql` | | `db.operation` | string | The name of the operation being executed, e.g. the MongoDB command name such as findAndModify, or the SQL keyword. Based on [OpenTelemetry's database semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/) | `SELECT` | | `db.collection.name` | string | The name of the collection (or table, etc) being queried. | `users` | | `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). | `customers` | | `server.address` | string | Name of the database host. | `example.com` | | `server.port` | int | Logical server port number host. | `8080` | | `server.socket.address` | string | Physical server IP address or Unix socket address. host. | `10.5.3.2` | | `server.socket.port` | int | Physical server port. host. | `16456` | ## [Web Server](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#web-server) | Attribute | Type | Description | Examples | | ---------------------- | ------- | ---------------------------------------------------------- | ---------------------- | | `cache.hit` | boolean | If the cache was hit during this span. | `true` | | `cache.key` | array | The cache key(s) involved in the operation. | `['posts']` | | `cache.operation` | string | The specific cache operation that was performed. | `get` | | `cache.write` | boolean | Whether the operation resulted in writing to the cache. | `false` | | `cache.item_size` | int | The size of the requested item in the cache, in bytes. | `58` | | `cache.success` | boolean | Whether the cache operation succeeded. | `true` | | `cache.ttl` | int | The time-to-live for the cache entry, in seconds. | `300` | | `network.peer.address` | string | Hostname of the cache instance that handled the operation. | `cache.internal.local` | | `network.peer.port` | int | Port of the cache instance that handled the operation. | `6379` | ## [AI](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#ai) | Attribute | Type | Description | Examples | | --------------------------- | ------- | ----------------------------------------------------- | ---------------------------------------- | | `ai.input_messages` | string | The input messages sent to the model | `[{"role": "user", "message": "hello"}]` | | `ai.completion_tоkens.used` | int | The number of tokens used to respond to the message | `10` | | `ai.prompt_tоkens.used` | int | The number of tokens used to process just the prompt | `20` | | `ai.total_tоkens.used` | int | The total number of tokens used to process the prompt | `30` | | `ai.model_id` | list | The vendor-specific ID of the model used | `"gpt-4"` | | `ai.streaming` | boolean | Whether the request was streamed back | `true` | | `ai.responses` | list | The response messages sent back by the AI model | `["hello", "world"]` | ## [Thread](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#thread) | Attribute | Type | Description | Examples | | ------------- | ------ | ---------------------------------------------------------- | -------- | | `thread.id` | string | Identifier of a thread from where the span originated. | `123456` | | `thread.name` | string | Label identifying a thread from where the span originated. | `main` | ## [Flags](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#flags) | Attribute | Type | Description | Examples | | ----------------------------- | ------ | ----------------------------------------------- | ------------ | | `flag.evaluation.` | string | Identifier of a flag evaluated within the span. | `can_access` | ### [Deprecated](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md#deprecated) Names that SDKs are still sending so we cannot remove them yet, but should not be used in new code. | Attribute | New name | | ------------------- | ----------------------------------- | | `method` | `http.request.method` | | `http.method` | `http.request.method` | | `Encoded Body Size` | `http.response_content_length` | | `Decoded Body Size` | `http.decoded_response_body_length` | | `Transfer Size` | `http.response_transfer_size` |