Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-open: Clarify that service.* conventions apply to all telemetry sources #671

Closed
wants to merge 1 commit into from
Closed

Re-open: Clarify that service.* conventions apply to all telemetry sources #671

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ release.

### Fixes

- Clarify that `service.*` attributes apply to all telemetry sources.
([#630](https://github.com/open-telemetry/semantic-conventions/pull/630))

## v1.24.0 (2023-12-15)

### Breaking
Expand Down
4 changes: 2 additions & 2 deletions docs/resource/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet

**type:** `service`

**Description:** A service instance.
**Description:** A telemetry source. OpenTelemetry has adopted a broad interpretation such that every telemetry source is a service. Examples include, but are not limited to: web services, hosts, mobile applications, browser application, edge computing devices, functions as a service, databases, message brokers, etc. Specific types of telemetry sources may have additional conventions defining domain specific information, but the `service` conventions are applicable to all telemetry sources.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would qualify as telemetry source when scraping metrics from a Kubernetes cluster? Is it the cluster component responsible for creating and providing the metrics (the "source" in a technical sense)? Or is it a deployment, node, or container (the entity a piece of telemetry data primarily refers to, in a logical sense)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its a good question and probably a key aspect of the design of the scraping component. The prometheus model (commonly used to scrape metrics from k8s clusters) every endpoint scraped is an "instance", and multiple replicated endpoints of an instance are a "job". These ideas map well to the idea of service.name (i.e. prometheus job) and service.instance.id (i.e. prometheus instance). The next question is can the scraper ascribe any other useful bits of information describing / identifying the telemetry source? I.e. does it know its scraping information about a node, deployment, or pod, or does everything role up into just a cluster?

The idea of a common set of identifying resource attributes applicable across all telemetry sources works nicely with the #575 idea of adding a service.type attribute. With these in place, a OTLP receiver can reliably know the identity and type of telemetry producer.

The next question to answer is how correlation works: If all telemetry sources have the same identifying attributes, how do we indicate that a service is running on a host in a cluster? We have attributes for a host and cluster, but when everything uses service.* for identity, we need conventions about how a host and a cluster populate the service.* attributes.

For example, consider a setup with a service running on a host. Both the service and host are telemetry producers:

// Host resource
{ service.name: "jberg", service.instance.id: "abc123", service.type: "host" }

// Service resource
{ service.name: "my-service", "service.instance.id: "def456", service.type: "web_service", host.name: "jberg", host.id: "abc123" }

If we have a convention that states that hosts set service.name=${host.name}, service.instance.id=${host.id}, service.type=host, then we can reliably known that "my-service" is running on the host because it has matching host.name, host.id resource attributes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, so service.type would identify the kind of entity that service attributes refer to.

However, it seems to me that with its current proposed definition it doesn't fully cover this use case:

The service.type identifies the product that is deployed as the service.

A value like "host" doesn't match that description, the proposed definition of service.type would need to be generalized to account for that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. This PR doesn't solve all the problems associated with identifying and correlating telemetry sources. It aims to codify just one concept (which I assert we already imply) - that all telemetry sources use the same attributes for identity - which we can build off of in future steps.


<!-- semconv service -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand All @@ -94,7 +94,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet

**type:** `service`

**Description:** Additions to service instance.
**Description:** Experimental additions to service.

<!-- semconv service_experimental -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand Down
7 changes: 6 additions & 1 deletion model/resource/service.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,12 @@ groups:
prefix: service
type: resource
brief: >
A service instance.
A telemetry source. OpenTelemetry has adopted a broad interpretation such that every
telemetry source is a service. Examples include, but are not limited to: web services,
hosts, mobile applications, browser application, edge computing devices, functions as
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
hosts, mobile applications, browser application, edge computing devices, functions as
hosts, mobile applications, browser applications, edge computing devices, functions as

a service, databases, message brokers, etc. Specific types of telemetry sources may have
additional conventions defining domain specific information, but the `service`
conventions are applicable to all telemetry sources.
attributes:
- id: name
type: string
Expand Down
2 changes: 1 addition & 1 deletion model/resource/service_experimental.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ groups:
prefix: service
type: resource
brief: >
A service instance.
Experimental additions to service.
attributes:
- id: namespace
type: string
Expand Down
Loading