Hello! Today, we’re going to dive deep into one of the core concepts of OpenTelemetry, an essential in the era of MSA (Microservices Architecture): Semantic Conventions. They’re like magical rules that transform complex system data into easy-to-understand information! β¨
π€ Data is Abundant… So Why is Analysis Difficult?
The services we operate consist of numerous components (web servers, API gateways, databases, etc.). They each pour out log, metric, and trace data in different ways.
- Service A: Stores HTTP status codes under the name
status - Service B: Stores HTTP status codes under the name
http_code - Service C: Stores HTTP status codes under the name
response.code
Doesn’t just imagining it give you a headache? π€― When data attribute names are all over the place like this, it becomes very difficult to grasp the overall system status at a glance and analyze it. Even a simple question like “How many 500 errors occurred across all services?” becomes hard to answer.
π Semantic Conventions: The Standard Language of the Data World
To resolve this confusion, OpenTelemetry offers Semantic Conventions as the solution.
What are Semantic Conventions? π They are agreements (specifications) that standardize the names of attributes in telemetry data collected by OpenTelemetry. It’s easy to think of it as a global consensus among developers saying, “Let’s call this data by this name!”
Simply put, it’s about unifying the labels attached to data, ensuring that no matter who collects the data, where, or with what technology, it maintains a consistent format.
π Practical Examples of Semantic Conventions
Does it not quite click just by hearing about it? Let’s look at some common examples.
1. HTTP Request Data β‘οΈ
HTTP requests are the most common way our services communicate externally! Semantic Conventions define attribute names as follows:
http.method: HTTP request method (e.g.,GET,POST)http.url: Full request URL (e.g.,http.status_code: HTTP response status code (e.g.,200,404,500)http.user_agent: User-Agent information of the client that sent the request
Now, no matter which service collects HTTP data, the status code will always be stored under the name http.status_code. Very convenient, isn’t it?
2. Database Call Data ποΈ
The same applies when applications communicate with databases.
db.system: Type of database used (e.g.,mysql,postgresql,redis)db.statement: Actual query executed (e.g.,SELECT * FROM users WHERE id = ?)db.user: Username used to connect to the databasedb.name: Name of the database instance connected to
Thanks to these unified names, we can easily find answers to questions like, “Which db.system is executing an unusually high number of slow db.statements?”
π Benefits of Using Semantic Conventions
- Ensuring Data Consistency π Even if different languages (Java, Python, Go) or frameworks are used, the collected data attribute names remain consistent, allowing for the construction of a uniform data pipeline.
- Ease of Analysis and Visualization π It’s much more convenient to analyze data in visualization tools like Grafana and Jaeger. You can create a dashboard to find all requests with
http.status_code500 or higher just once, and apply it uniformly across all services. - Excellent Interoperability π€ All tools and vendors in the OpenTelemetry ecosystem adhere to these Semantic Conventions. Therefore, regardless of the analysis tool used, data can be immediately understood and utilized without separate parsing or conversion.
Conclusion
Semantic Conventions go beyond simply unifying data attribute names; they play a crucial role in bringing order to the chaos of data generated in complex, intertwined microservices environments. If you aim to build successful Observability with OpenTelemetry, understanding Semantic Conventions is not an option, but a necessity! π
Leave a Reply