To properly associate measurements to the same "dimension" so that correlation algorithms work effectively, here are a list of attributes which agents should produce. Attributes marked as required are necessary for some form of event association support on the backend. Attributes marked as recommended are strongly encouraged for good association support by the backend processors.
| Attribute | Type | Description | Examples | Requirement Level | Stability |
|---|---|---|---|---|---|
service.instance.id |
string | The string ID of the service instance. [1] | 627cc493-f310-47de-96bd-71410b7dec09 |
Required |
 |
service.name |
string | Logical name of the service. [2] | shoppingcart |
Required |
 |
telemetry.sdk.language |
string | The language of the telemetry SDK. | cpp; dotnet; erlang |
Required |
|
telemetry.sdk.name |
string | The name of the telemetry SDK as defined above. [3] | opentelemetry; contrast |
Required |
|
telemetry.sdk.version |
string | The version string of the telemetry SDK. | 1.2.3 |
Required |
|
http.request.method |
string | HTTP request method. [4] | GET; POST; HEAD |
Conditionally Required iff observation is scoped to an http request |
|
http.route |
string | The matched route (path template in the format used by the respective server framework). See note below [5] | /users/:userID?; {controller}/{action}/{id?} |
Conditionally Required iff observation is scoped to an http request |
|
cloud.provider |
string | Name of the cloud provider. | alibaba_cloud; aws; azure |
Recommended |
|
cloud.region |
string | The geographical region the resource is running. [6] | us-central1; us-east-1 |
Recommended |
|
cloud.resource_id |
string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an ARN on AWS, a fully qualified resource ID on Azure, a full resource name on GCP) [7] | arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function; //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID; /subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC> |
Recommended |
|
contrast.deployment |
string | deployment environment | QA; DEVELOPMENT; PRODUCTION |
Recommended |
|
contrast.semconv.version |
string | The version of contrast semantic conventions the data adheres to. | 0.3.0 |
Recommended |
|
otel.semconv.version |
string | The version of otel semantic conventions the data adheres to. | 1.22.0 |
Recommended |
|
service.namespace |
string | A namespace for service.name. [8] |
Shop |
Recommended |
|
service.version |
string | The version string of the service API or implementation. The format is not defined by these conventions. | 2.0.0; a01dbef8a |
Recommended |
|
telemetry.distro.name |
string | The name of the auto instrumentation agent or distribution, if used. [9] | contrast-java |
Recommended |
|
telemetry.distro.version |
string | The version string of the auto instrumentation agent or distribution, if used. | 1.2.3 |
Recommended |
|
[1] service.instance.id: MUST be unique for each instance of the same service.namespace,service.name pair (in other words
service.namespace,service.name,service.instance.id triplet MUST be globally unique). The ID helps to
distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled
service).
Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 RFC
4122 UUID, but are free to use an inherent unique ID as the source of
this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and
SHOULD use the following UUID as the namespace: 4d63009a-8d0f-11ee-aad7-4c796ed8e320.
UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is
needed. Similar to what can be seen in the man page for the
/etc/machine-id file, the underlying
data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it
or not via another resource attribute.
For applications running behind an application server (like unicorn), we do not recommend using one identifier for all processes participating in the application. Instead, it's recommended each division (e.g. a worker thread in unicorn) to have its own instance.id.
It's not recommended for a Collector to set service.instance.id if it can't unambiguously determine the
service instance that is generating that telemetry. For instance, creating an UUID based on pod.name will
likely be wrong, as the Collector might not know from which container within that pod the telemetry originated.
However, Collectors can set the service.instance.id if they can unambiguously determine the service instance
for that telemetry. This is typically the case for scraping receivers, as they know the target address and
port.
[2] service.name: MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to unknown_service: concatenated with process.executable.name, e.g. unknown_service:bash. If process.executable.name is not available, the value MUST be set to unknown_service.
[3] telemetry.sdk.name: The OpenTelemetry SDK MUST set the telemetry.sdk.name attribute to opentelemetry.
If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the
telemetry.sdk.name attribute to the fully-qualified class or module name of this SDK's main entry point
or another suitable identifier depending on the language.
The identifier opentelemetry is reserved and MUST NOT be used in this case.
All custom identifiers SHOULD be stable across different versions of an implementation.
[4] http.request.method: HTTP request method value SHOULD be "known" to the instrumentation.
By default, this convention defines "known" methods as the ones listed in RFC9110
and the PATCH method defined in RFC5789.
If the HTTP request method is not known to instrumentation, it MUST set the http.request.method attribute to _OTHER.
If the HTTP instrumentation could end up converting valid HTTP request methods to _OTHER, then it MUST provide a way to override
the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
HTTP method names are case-sensitive and http.request.method attribute value MUST match a known HTTP method name exactly.
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
Tracing instrumentations that do so, MUST also set http.request.method_original to the original value.
[5] http.route: MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the application root if there is one.
[6] cloud.region: Refer to your provider's docs to see the available regions, for example Alibaba Cloud regions, AWS regions, Azure regions, Google Cloud regions, or Tencent Cloud regions.
[7] cloud.resource_id: On some cloud providers, it may not be possible to determine the full ID at startup,
so it may be necessary to set cloud.resource_id as a span attribute instead.
The exact value to use for cloud.resource_id depends on the cloud provider.
The following well-known definitions MUST be used if you set this attribute and they apply:
- AWS Lambda: The function ARN. Take care not to use the "invoked ARN" directly but replace any alias suffix with the resolved function version, as the same runtime instance may be invocable with multiple different aliases.
- GCP: The URI of the resource
- Azure: The Fully Qualified Resource ID of the invoked function,
not the function app, having the form
/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>. This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider.
[8] service.namespace: A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. service.name is expected to be unique within the same namespace. If service.namespace is not specified in the Resource then service.name is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
[9] telemetry.distro.name: Official auto instrumentation agents and distributions SHOULD set the telemetry.distro.name attribute to
a string starting with opentelemetry-, e.g. opentelemetry-java-instrumentation.
cloud.provider has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
alibaba_cloud |
Alibaba Cloud | |
aws |
Amazon Web Services | |
azure |
Microsoft Azure | |
gcp |
Google Cloud Platform | |
heroku |
Heroku Platform as a Service | |
ibm_cloud |
IBM Cloud | |
tencent_cloud |
Tencent Cloud | |
contrast.deployment has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
DEVELOPMENT |
development environment | |
PRODUCTION |
production environment | |
QA |
quality assurance environment | |
http.request.method has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
_OTHER |
Any HTTP method that the instrumentation has no prior knowledge of. | |
CONNECT |
CONNECT method. | |
DELETE |
DELETE method. | |
GET |
GET method. | |
HEAD |
HEAD method. | |
OPTIONS |
OPTIONS method. | |
PATCH |
PATCH method. | |
POST |
POST method. | |
PUT |
PUT method. | |
TRACE |
TRACE method. | |
telemetry.sdk.language has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
cpp |
cpp | |
dotnet |
dotnet | |
erlang |
erlang | |
go |
go | |
java |
java | |
nodejs |
nodejs | |
php |
php | |
python |
python | |
ruby |
ruby | |
rust |
rust | |
swift |
swift | |
webjs |
webjs | |