Semantic Conventions in OpenTelemetry
In this article, we’re going to learn about semantic conventions in OpenTelemetry and how they are used to make data processing much easier. We’ll also discuss the different types of semantic conventions. without further ado let's get started.
What Are Semantic Conventions?
Semantic conventions in general are the agreed-upon meaning of words and phrases within a particular language or culture. They help us communicate with each other by providing a shared understanding of our symbols.
For example, the “thumbs up” gesture is a convention that means “good job” or “I agree” in many cultures.
Without these conventions, communication would be much more difficult; we would constantly have to explain the meaning of every single word we use.
What Do Semantic Conventions Mean In OpenTelemetry?
Semantic conventions are important in OpenTelemetry because they help to define the meaning of resources and metrics. Semantic conventions provide a common language for all users of the system. This allows for a more accurate interpretation of data and helps to ensure that everyone is on the same page when it comes to resource usage and performance.
In this lesson, We will take a quick look at the different kinds of semantic conventions provided by Opentelemetry. Let’s start with metric semantic conventions,
What Are Metric Semantic Conventions?
The OpenTelemetry project has published a set of metric semantic conventions that can be used by any software that collects or displays metrics data.
The metric semantic conventions define a set of core dimensions that should be used when recording metric data. These dimensions include name, description, unit, and type. In addition, the conventions define a set of recommended labels that can be used to further describe the data. By following these standards, it is possible to create easily understood metrics that can be effectively compared.
A quick example for naming conventions is limit which means the known total amount of something. For example, system.memory.limit for the total amount of memory on a system.
utilization - means the fraction of usage out of its limit should be called entity.utilization. For example, system.memory.utilization for the fraction of memory in use. Utilization values are in the range [0, 1].
For more information about metric semantic conventions, please check the official documentation of opentelemetry from here
In addition to the metric semantic conventions, the OpenTelemetry team has also published standards for logging and tracing data. By using these standards, it is possible to create software that can generate consistent results regardless of the underlying implementation.
Let’s take a closer look at semantic conventions for spans and traces.
semantic conventions for spans and traces
It’s recommended to use attributes to describe the dimensions of the telemetry data collected. For example, when dealing with network data, attributes might describe the source and destination IP address, the port numbers, etc. Attributes can also be used to describe metadata about the data itself. For example, when dealing with log data, attributes might describe the timestamp, the logging level, etc.
Attributes are stored in so-called AttributeMaps. An AttributeMap is a map from attribute keys to attribute values. The keys are typically strings, but they can also be other data types. The values can be any data type that can be represented as a JSON value.
One of the benefits of using attributes is that they provide a way to add additional information to the data without changing the data itself. This is especially useful when dealing with legacy systems that cannot be modified.
Another benefit of attributes is that they can be used to filter and group data. For example, if one has a log file that contains messages from multiple sources, they can use attributes to filter out messages from certain sources. Or, if they want to group all messages with the same logging level, they can use attributes.
Here is an example of manually defining attributes for a service
# Resource attributes that describe a service.
namespace = Company.Shop
service.name = shoppingcartEvents
Events are one of the core concepts in OpenTelemetry, providing a way to record significant moments or states in the system that can be used for monitoring and analysis. They can be generated manually by operators or automatically by the OpenTelemetry SDK. OpenTelemetry events contain metadata about the event and any relevant data that was collected at the time of the event.
Events can be used to track the progress of a system through its lifecycle or to identify changes in state that may indicate an issue. They can also be used to record performance data, such as response times or resource utilization. By analyzing events, it is possible to understand how a system is functioning and where potential problems may lie.
Here is an example event in a span
{
"name": "Hello",
"context": {
"trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2",
"span_id": "0x051581bf3cb55c13"
},
"parent_id": null,
"start_time": "2023-01-19T18:52:58.114201Z",
"end_time": "2023-01-19T18:52:58.114687Z",
"attributes": {
"namespace": "Company.Shop",
"service.name": "shoppingcart"
},
"events": [
{
"name": "Guten Tag!",
"timestamp": "2023-01-19T18:52:58.114561Z",
"attributes": {
"event_attributes": 12
}
}
]
}The event here has a name, timestamp and some attributes.
Conclusion
Semantic conventions are important in OpenTelemetry because they provide a common language for all users of the system. The OpenTelemetry project has published a set of metric semantic conventions that can be used by any software that collects or displays metrics data. In addition, the OpenTelemetry team has also published standards for logging and tracing data. By using these standards, it is possible to create software that can generate consistent results regardless of the underlying implementation.
To learn more Semantic Conventions, Please check official OpenTelemetry documentation:
