OpenTelemetry Fields and Attributes¶
This document defines the OpenTelemetry fields and attributes used by the Observability package.
It sits between the Metrics Catalogue and the Field Matrix.
The Metrics Catalogue defines what telemetry is required.
This document defines the OpenTelemetry vocabulary used to represent that telemetry.
The Field Matrix will subsequently reconcile these OpenTelemetry fields with:
- Prometheus metric fields
- Loki log fields
- Jaeger trace fields
- Canonical organizational fields
- The minimum Observability ontology
This document does not define dashboard behavior and does not define the final canonical ontology.
1. Scope¶
The current inventory covers:
- Resource attributes
- HTTP server attributes
- HTTP client attributes
- Database attributes
- Redis attributes
- Process attributes
- Runtime attributes
- System attributes
- Log fields
- Trace fields
The inventory distinguishes between:
- Fields explicitly established by the current implementation
- Fields referenced by the dashboard contract
- Fields expected from OpenTelemetry semantic conventions but requiring implementation verification
2. Attribute Categories¶
OpenTelemetry telemetry can carry information at several levels.
Resource
↓
Scope
↓
Signal
├── Metrics
├── Logs
└── Traces
The distinction is important.
A resource attribute describes the entity producing telemetry.
A metric attribute describes a dimension of a measurement.
A span attribute describes a particular operation.
A log field describes a particular log record.
The same conceptual information may therefore appear at different levels.
For example:
service.name
is fundamentally a resource attribute, while:
http.request.method
describes an individual HTTP operation.
3. Resource Attributes¶
The current build_resource() implementation creates the following resource attributes.
| Attribute | Type | Current Source | Status | Description |
|---|---|---|---|---|
service.name |
string | ObservabilityConfig.service_name |
Implemented | Logical name of the instrumented service |
service.version |
string | ObservabilityConfig.service_version |
Implemented | Version of the deployed service |
deployment.environment |
string | OTEL_ENVIRONMENT |
Implemented | Deployment environment |
service.instance.id |
string | Generated UUID | Implemented | Unique identifier for the running service instance |
host.name |
string | socket.gethostname() |
Implemented | Host on which the process is running |
host.arch |
string | platform.machine() |
Implemented | Host architecture |
os.type |
string | platform.system() |
Implemented | Operating system type |
process.pid |
integer | os.getpid() |
Implemented | Operating system process identifier |
process.runtime.name |
string | platform.python_implementation() |
Implemented | Runtime implementation |
process.runtime.version |
string | platform.python_version() |
Implemented | Runtime version |
The resource is created once and attached to the telemetry providers.
Conceptually:
Resource
├── service.name
├── service.version
├── deployment.environment
├── service.instance.id
├── host.name
├── host.arch
├── os.type
├── process.pid
├── process.runtime.name
└── process.runtime.version
4. Service Identity Attributes¶
Service identity is central to all three observability signals.
| Attribute | Type | Level | Purpose |
|---|---|---|---|
service.name |
string | Resource | Identifies the logical service |
service.version |
string | Resource | Identifies the deployed version |
service.instance.id |
string | Resource | Identifies a particular running instance |
deployment.environment |
string | Resource | Identifies the deployment environment |
These fields are expected to provide the primary identity dimensions used by dashboards and telemetry backends.
The current dashboard implementation additionally uses the Prometheus label:
exported_job
This is an exported/backend representation and should not automatically be treated as an OpenTelemetry semantic attribute.
The Field Matrix must explicitly document the relationship between:
service.name
↓
exported_job
rather than treating the two names as interchangeable.
5. HTTP Server Attributes¶
HTTP server instrumentation describes inbound requests.
The current dashboard contract identifies the following dimensions:
| Dashboard Field | OTel Concept | Type | Current Status |
|---|---|---|---|
http_method |
HTTP request method | string | Implementation requires verification |
http_status_code |
HTTP response status | integer | Implementation requires verification |
http_target |
HTTP target | string | Implementation requires verification |
http_route |
HTTP route | string | Referenced by dashboards, requires verification |
The current Metrics Catalogue uses:
http_method
http_status_code
http_target
while some dashboard specifications use:
http_route
http_method
http_status_code
This discrepancy is intentionally preserved here.
It must be resolved in the Field Matrix rather than silently changing the catalogue.
The expected conceptual mapping is:
HTTP request
├── method
├── route
├── target
└── response status
6. HTTP Server Metric Dimensions¶
The HTTP server metrics currently depend on the following dimensions.
6.1 HTTP Method¶
| Property | Value |
|---|---|
| Dashboard representation | http_method |
| Concept | HTTP request method |
| Example values | GET, POST, PUT, DELETE |
| Signal | Metrics |
| Status | Requires implementation verification |
Used to distinguish request traffic by HTTP method.
6.2 HTTP Response Status¶
| Property | Value |
|---|---|
| Dashboard representation | http_status_code |
| Concept | HTTP response status code |
| Example values | 200, 201, 400, 404, 500 |
| Signal | Metrics |
| Status | Requires implementation verification |
Used for:
- Error rate
- Status distribution
- Error endpoint analysis
6.3 HTTP Target¶
| Property | Value |
|---|---|
| Dashboard representation | http_target |
| Concept | Requested HTTP target |
| Signal | Metrics |
| Status | Requires implementation verification |
The target should be treated carefully because raw targets may introduce high cardinality.
6.4 HTTP Route¶
| Property | Value |
|---|---|
| Dashboard representation | http_route |
| Concept | Normalized application route |
| Signal | Metrics / traces |
| Status | Referenced by dashboard specification |
| Cardinality | Expected to be bounded by application routes |
The normalized route is preferred for endpoint-level dashboard analysis over raw request URLs.
7. HTTP Client Attributes¶
HTTPX instrumentation provides telemetry for outbound HTTP requests.
The current Metrics Catalogue identifies:
| Dashboard Field | Concept | Type | Status |
|---|---|---|---|
http_request_method |
Outbound HTTP method | string | Requires verification |
http_response_status_code |
Outbound response status | integer | Requires verification |
server_address |
Downstream server | string | Requires verification |
These dimensions support the External Services dashboard.
Conceptually:
HTTP Client Request
├── request method
├── destination server
└── response status
8. HTTP Client Method¶
| Property | Value |
|---|---|
| Dashboard representation | http_request_method |
| Concept | HTTP request method |
| Signal | Metrics / traces |
| Example values | GET, POST, PUT, DELETE |
| Status | Requires implementation verification |
Used to calculate outbound request rates by method.
9. HTTP Client Response Status¶
| Property | Value |
|---|---|
| Dashboard representation | http_response_status_code |
| Concept | HTTP response status code |
| Signal | Metrics / traces |
| Status | Requires implementation verification |
Used to distinguish successful and failed downstream calls.
10. HTTP Client Destination¶
| Property | Value |
|---|---|
| Dashboard representation | server_address |
| Concept | Destination server address |
| Signal | Metrics / traces |
| Status | Requires implementation verification |
Used by:
HTTPCLIENT.TOP_DEPENDENCIES
to identify frequently accessed external services.
The Field Matrix should later determine whether this backend field represents a host, service, or another destination concept.
11. Database Attributes¶
Database instrumentation is provided through SQLAlchemy and psycopg2 integrations.
The current catalogue references:
db_operation
db_system_name
db_name
These represent three distinct dimensions.
11.1 Database System¶
| Property | Value |
|---|---|
| Dashboard field | db_system_name |
| Concept | Database system |
| Example values | PostgreSQL, Redis |
| Signal | Metrics / traces |
| Status | Requires implementation verification |
The system identifies the technology executing the database operation.
11.2 Database Operation¶
| Property | Value |
|---|---|
| Dashboard field | db_operation |
| Concept | Database operation |
| Signal | Metrics / traces |
| Example values | SELECT, INSERT, UPDATE, DELETE |
| Status | Requires implementation verification |
Used to distinguish database operation types.
11.3 Database Name¶
| Property | Value |
|---|---|
| Dashboard field | db_name |
| Concept | Database name |
| Signal | Metrics / traces |
| Status | Requires implementation verification |
Identifies the logical database involved in the operation.
12. Redis Attributes¶
Redis currently shares the database client metric namespace.
The catalogue identifies:
db_operation
db_system_name
for Redis telemetry.
Conceptually:
Redis Operation
├── system
└── operation
Examples of operations include:
GET
SET
DEL
HGET
EXPIRE
The exact attribute names emitted by the Redis instrumentation must be verified against the installed instrumentation version.
13. Process Attributes¶
The resource builder establishes process identity.
The current fields are:
| Attribute | Type | Description |
|---|---|---|
process.pid |
integer | Operating system process identifier |
process.runtime.name |
string | Runtime implementation |
process.runtime.version |
string | Runtime version |
The Metrics Catalogue additionally defines process-level measurements:
process_cpu_utilization_ratio
process_cpu_time_seconds_total
process_memory_usage_bytes
process_memory_virtual_bytes
process_runtime_start_time
process_thread_count
process_open_file_descriptor_count
The distinction is:
Process Attributes
↓
Describe the process
Process Metrics
↓
Measure the process
14. Runtime Attributes¶
The current Python implementation provides:
| Attribute | Type | Example |
|---|---|---|
process.runtime.name |
string | CPython |
process.runtime.version |
string | 3.x |
These identify the runtime executing the service.
The runtime metrics catalogue additionally includes CPython garbage collection measurements.
15. Python Garbage Collection Attributes¶
The current metrics catalogue identifies the following dimensions conceptually:
generation
for garbage collection metrics in the earlier dashboard design.
The reconciled catalogue currently does not include generation as a metric label.
This is intentional.
The implementation must first establish whether generation is emitted as a metric attribute before it becomes part of the canonical metric contract.
The current inventory therefore treats:
cpython_gc_collections_total
cpython_gc_collected_objects_total
cpython_gc_uncollectable_objects_total
as metrics whose dimensionality still requires verification.
16. System Attributes¶
System metrics currently include:
system_memory_utilization_ratio
system_network_io_bytes_total
system_disk_io_bytes_total
The network and disk metrics use:
direction
as a dimension.
Typical conceptual values are:
receive
transmit
or equivalent instrumentation-specific representations.
The exact values must be verified from the emitted telemetry.
17. Network Direction¶
| Property | Value |
|---|---|
| Field | direction |
| Signal | Metrics |
| Used By | System Network I/O |
| Purpose | Distinguishes network traffic direction |
| Status | Requires implementation verification |
The direction attribute should be treated as a controlled vocabulary rather than arbitrary user-defined text.
18. Disk Direction¶
The disk I/O metric also uses:
direction
to distinguish read and write operations.
Conceptually:
read
write
The exact emitted values require implementation verification.
19. Logging Fields¶
The current logging contract requires the following fields.
| Field | Category | Purpose |
|---|---|---|
service.name |
Resource | Identifies service |
deployment.environment |
Resource | Identifies environment |
severity |
Log field | Identifies log severity |
trace_id |
Correlation field | Associates log with trace |
span_id |
Correlation field | Associates log with span |
The logging provider is configured using:
LoggingHandler(
level=level,
logger_provider=provider
)
and Python logging is instrumented with:
LoggingInstrumentor().instrument(
set_logging_format=False
)
The current implementation specifically intends to inject trace and span identifiers into Python log records.
20. Log Severity¶
| Property | Value |
|---|---|
| Field | severity |
| Signal | Logs |
| Purpose | Represents log severity |
| Examples | INFO, WARNING, ERROR |
| Status | Required by dashboard contract |
The exact exported field representation should be validated against the OTLP log payload and Loki ingestion pipeline.
21. Trace Correlation Fields¶
The following identifiers connect logs to traces.
| Field | Purpose |
|---|---|
trace_id |
Identifies the complete distributed request |
span_id |
Identifies the specific operation within the trace |
Conceptually:
Trace
└── trace_id
├── Span
│ └── span_id
├── Span
│ └── span_id
└── Span
└── span_id
Logs generated while a span is active can therefore be correlated with the corresponding trace and span.
22. Trace Attributes¶
The Traces dashboard currently requires:
| Field | Concept | Status |
|---|---|---|
service.name |
Service identity | Implemented as resource |
span.name |
Operation identity | Instrumentation dependent |
trace_id |
Distributed trace identity | OTel trace context |
span_id |
Span identity | OTel trace context |
duration |
Span duration | Span data |
status |
Span outcome | Instrumentation dependent |
The exact representation of span status must be validated against the tracing backend.
23. Span Kind¶
The Traces dashboard uses the concept:
span.kind="client"
to identify outbound operations.
This allows the dashboard to distinguish client spans from server or internal spans.
The concept is especially important for:
- HTTPX calls
- Database operations
- Redis operations
The exact exported representation must be verified against the Jaeger data model.
24. Database Trace Attributes¶
Database spans are expected to provide database-related context.
The current dashboard specification references:
db.system
and database operation information.
The current catalogue uses:
db_system_name
db_operation
db_name
These should not yet be assumed to be identical.
The Field Matrix must explicitly reconcile:
Dashboard field
↓
Prometheus field
↓
OTel attribute
↓
Jaeger field
25. Redis Trace Attributes¶
Redis spans are expected to identify:
db.system="redis"
and the Redis operation being executed.
The Traces dashboard uses this information to isolate Redis activity within a distributed request.
26. GenAI Attributes¶
The current implementation prepares for GenAI instrumentation by setting:
OTEL_SEMCONV_STABILITY_OPT_IN
to:
gen_ai_latest_experimental
The configuration also exposes:
OTEL_GENAI_CAPTURE_CONTENT
through:
genai_capture_content
with a default of False.
This indicates that GenAI telemetry is an intended future extension of the Observability package.
However, no GenAI metric or attribute family is currently included in the reconciled Metrics Catalogue.
Therefore this document does not yet establish a canonical GenAI field inventory.
Future GenAI fields should be added only after the instrumentation and semantic convention being used are established.
27. Configuration Fields¶
The Observability configuration exposes several operational settings that affect telemetry generation.
These are configuration fields rather than telemetry attributes.
| Configuration | Purpose |
|---|---|
OTEL_ENVIRONMENT |
Deployment environment |
OTEL_EXPORTER_OTLP_ENDPOINT |
OTLP destination |
OTEL_EXPORTER_OTLP_HEADERS |
OTLP authentication and metadata |
OTEL_TRACES_ENABLED |
Enables tracing |
OTEL_METRICS_ENABLED |
Enables metrics |
OTEL_LOGS_ENABLED |
Enables logs |
OTEL_LOG_LEVEL |
Python logging level |
OTEL_GENAI_CAPTURE_CONTENT |
Controls GenAI content capture |
These fields should not be confused with telemetry attributes.
For example:
OTEL_ENVIRONMENT
↓
configuration
deployment.environment
↓
telemetry resource attribute
28. Attribute Cardinality¶
Attributes used on metrics must have controlled cardinality.
The following are generally suitable dimensions:
service.name
deployment.environment
http_method
http_status_code
http_route
db_operation
db_system
direction
The following should be treated with caution:
http_target
server_address
db_name
The following should generally not become metric dimensions without explicit justification:
trace_id
span_id
user_id
request_id
raw URL
SQL statement
request body
response body
exception message
High-cardinality identifiers belong primarily in traces and logs rather than metric labels.
29. Metric Attributes Versus Resource Attributes¶
The implementation must preserve the distinction between resource identity and metric dimensions.
For example:
service.name
deployment.environment
service.instance.id
identify the telemetry-producing entity.
By contrast:
http_method
http_status_code
http_route
describe individual request dimensions.
Conceptually:
Resource
├── service.name
├── service.version
├── deployment.environment
└── service.instance.id
Metric
├── HTTP method
├── HTTP route
└── HTTP status
This distinction becomes important when the telemetry is moved from Prometheus into another analytical database.
30. Current Attribute Inventory¶
The current inventory can be summarized as follows.
| Domain | Fields |
|---|---|
| Service | service.name, service.version, service.instance.id |
| Deployment | deployment.environment |
| Host | host.name, host.arch |
| Operating System | os.type |
| Process | process.pid, process.runtime.name, process.runtime.version |
| HTTP Server | method, route, target, response status |
| HTTP Client | request method, response status, server address |
| Database | system, operation, database name |
| Redis | system, operation |
| System | direction |
| Logs | severity, trace ID, span ID |
| Traces | span name, trace ID, span ID, duration, status, span kind |
31. Verification Status¶
Not every field in this inventory has been confirmed against the actual emitted telemetry.
The following are directly established by the current Python implementation:
service.nameservice.versiondeployment.environmentservice.instance.idhost.namehost.archos.typeprocess.pidprocess.runtime.nameprocess.runtime.version- Trace and span correlation through OpenTelemetry logging instrumentation
- System Metrics instrumentation being enabled
The following are established by the dashboard and metrics contracts but require runtime verification:
- HTTP metric attributes
- HTTP client metric attributes
- Database metric attributes
- Redis metric attributes
- Process metric dimensions
- System metric dimensions
- Exact exported names for several System Metrics
- Exact log field representation in Loki
- Exact trace field representation in Jaeger
This distinction is deliberate.
The Observability package should not encode an attribute as canonical merely because a dashboard query currently references it.
32. Relationship to the Field Matrix¶
This inventory is the vocabulary from which the Field Matrix will be constructed.
The Field Matrix should add the missing reconciliation layers:
OTel Attribute
↓
Prometheus Representation
↓
Loki Representation
↓
Jaeger Representation
↓
Canonical Field
↓
Canonical Mapping
↓
Ontology Concept
For example:
service.name
↓
exported_job
↓
service_name
↓
service.name
↓
Service
The exact mappings should be established in the Field Matrix rather than assumed here.
33. Next Step¶
The next artifact should be:
field-matrix.md
It should take every field in this inventory and answer:
- What is the OTel field?
- What signal does it belong to?
- Where is it emitted?
- What does Prometheus call it?
- What does Loki call it?
- What does Jaeger call it?
- What is its data type?
- What is its cardinality?
- What is its canonical field name?
- What minimum ontology concept does it belong to?
That is where we should resolve the current naming differences such as:
service.name
vs
exported_job
and:
http.request.method
vs
http_method
rather than prematurely forcing one naming scheme onto the implementation.