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 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 compatability.

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.

AttributeTypeDescriptionExamples
code.filepathstringThe 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.linenonumberThe line number in code.filepath best representing the operation. It SHOULD point within the code unit named in code.function42
code.functionstringThe method or function name, or equivalent (usually rightmost part of the code unit's name).server_request
code.namespacestringThe "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

AttributeTypeDescriptionExamples
http.querystringThe Query string present in the URL.?foo=bar&bar=baz
http.fragmentstringThe Fragments present in the URI (Browser SDKs only).#details
http.request.methodstringThe HTTP method used.GET
http.response.status_codeintThe status HTTP response.404
http.response_content_lengthnumberThe encoded body size of the response (in bytes).123
http.decoded_response_content_lengthnumberThe decoded body size of the response (in bytes).456
http.response_transfer_sizenumberThe transfer size of the response (in bytes).789
server.addressstringURL domain name.example.com
server.portintURL server port number8080

AttributeTypeDescriptionExamples
blocked_main_threadbooleanWhether the main thread was blocked by the span.true
call_stackStackFrame[]The most relevant stack frames, that lead to the File I/O span. The stack frame should adhere to the StackFrame interface.
urlstringThe URL of the resource that was fetched.https://example.com
typestringMore granular type of the operation happening.fetch
frames.totalintThe number of total frames rendered during the lifetime of the span.60
frames.slowintThe number of slow frames rendered during the lifetime of the span.2
frames.frozenintThe number of frozen frames rendered during the lifetime of the span.1
frames.delaynumberThe sum of all delayed frame durations in seconds during the lifetime of the span. For more information see frames delay.1.3246

AttributeTypeDescriptionExamples
urlstringThe URL of the resource that was fetched.https://example.com
typestringThe type of the resource that was fetched.xhr
resource.render_blocking_statusstringThe render blocking status of the resource.non-blocking

AttributeTypeDescriptionExamples
ui.contributes_to_ttidbooleanWhether the span execution contributed to the TTID (time to initial display) metric.true
ui.contributes_to_ttfdbooleanWhether the span execution contributed to the TTFD (time to fully drawn) metric.true

AttributeTypeDescriptionExamples
db.systemstringAn identifier for the database management system (DBMS) product being used. See OpenTelemetry docs for a list of well-known identifiers.postgresql
db.operationstringThe name of the operation being executed, e.g. the MongoDB command name such as findAndModify, or the SQL keyword. Based on OpenTelemetry's common db attributesSELECT
db.collection.namestringThe name of the collection (or table, etc) being queried.users
db.namestringThis 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.addressstringName of the database host.example.com
server.portintLogical server port number host.8080
server.socket.addressstringPhysical server IP address or Unix socket address. host.10.5.3.2
server.socket.portintPhysical server port. host.16456

AttributeTypeDescriptionExamples
cache.hitbooleanIf the cache was hit during this span.true
cache.item_sizeintThe size of the requested item in the cache. In bytes.58

AttributeTypeDescriptionExamples
ai.input_messagesstringThe input messages sent to the model[{"role": "user", "message": "hello"}]
ai.completion_tоkens.usedintThe number of tokens used to respond to the message10
ai.prompt_tоkens.usedintThe number of tokens used to process just the prompt20
ai.total_tоkens.usedintThe total number of tokens used to process the prompt30
ai.model_idlistThe vendor-specific ID of the model used"gpt-4"
ai.streamingbooleanWhether the request was streamed backtrue
ai.responseslistThe response messages sent back by the AI model["hello", "world"]

AttributeTypeDescriptionExamples
thread.idstringIdentifier of a thread from where the span originated.123456
thread.namestringLabel identifying a thread from where the span originated.main

Names that SDKs are still sending so we cannot remove them yet, but should not be used in new code.

AttributeNew name
methodhttp.request.method
http.methodhttp.request.method
Encoded Body Sizehttp.response_content_length
Decoded Body Sizehttp.decoded_response_body_length
Transfer Sizehttp.response_transfer_size
Previous
OpenTelemetry Support
Next
Span Operations
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").