tencent cloud

Tencent Cloud Observability Platform

Release Notes and Announcements
Release Notes
Product Introduction
Overview
Strengths
Basic Features
Basic Concepts
Use Cases
Use Limits
Purchase Guide
Tencent Cloud Product Monitoring
Application Performance Management
Mobile App Performance Monitoring
Real User Monitoring
Cloud Automated Testing
Prometheus Monitoring
Grafana
EventBridge
PTS
Quick Start
Monitoring Overview
Instance Group
Tencent Cloud Product Monitoring
Application Performance Management
Real User Monitoring
Cloud Automated Testing
Performance Testing Service
Prometheus Getting Started
Grafana
Dashboard Creation
EventBridge
Alarm Service
Cloud Product Monitoring
Tencent Cloud Service Metrics
Operation Guide
CVM Agents
Cloud Product Monitoring Integration with Grafana
Troubleshooting
Practical Tutorial
Application Performance Management
Product Introduction
Access Guide
Operation Guide
Practical Tutorial
Parameter Information
FAQs
Mobile App Performance Monitoring
Overview
Operation Guide
Access Guide
Practical Tutorial
Tencent Cloud Real User Monitoring
Product Introduction
Operation Guide
Connection Guide
FAQs
Cloud Automated Testing
Product Introduction
Operation Guide
FAQs
Performance Testing Service
Overview
Operation Guide
Practice Tutorial
JavaScript API List
FAQs
Prometheus Monitoring
Product Introduction
Access Guide
Operation Guide
Practical Tutorial
Terraform
FAQs
Grafana
Product Introduction
Operation Guide
Guide on Grafana Common Features
FAQs
Dashboard
Overview
Operation Guide
Alarm Management
Console Operation Guide
Troubleshooting
FAQs
EventBridge
Product Introduction
Operation Guide
Practical Tutorial
FAQs
Report Management
FAQs
General
Alarm Service
Concepts
Monitoring Charts
CVM Agents
Dynamic Alarm Threshold
CM Connection to Grafana
Documentation Guide
Related Agreements
Application Performance Management Service Level Agreement
APM Privacy Policy
APM Data Processing And Security Agreement
RUM Service Level Agreement
Mobile Performance Monitoring Service Level Agreement
Cloud Automated Testing Service Level Agreement
Prometheus Service Level Agreement
TCMG Service Level Agreements
PTS Service Level Agreement
PTS Use Limits
Cloud Monitor Service Level Agreement
API Documentation
History
Introduction
API Category
Making API Requests
Monitoring Data Query APIs
Alarm APIs
Legacy Alert APIs
Notification Template APIs
TMP APIs
Grafana Service APIs
Event Center APIs
TencentCloud Managed Service for Prometheus APIs
Monitoring APIs
Data Types
Error Codes
Glossary

APM Link Protocol Standard

PDF
フォーカスモード
フォントサイズ
最終更新日: 2026-01-08 15:23:56
This document will elaborate on the Link (Trace) protocol standard of Application Performance Management (APM). By participating in this protocol standard, users can obtain link data from the TencentCloud API DescribeGeneralOTSpanList, or enhance it with customized tracing points in applications to cover more frameworks and class libraries.

Link Protocol Design Principle

The link protocol design of Application Performance Monitoring (APM) follows the OpenTelemetry standard. For basic concepts of links, refer to OpenTelemetry Trace for more detailed information. If an application is accessed through the OpenTelemetry scheme, whether obtaining link data from the TencentCloud API or enhancing custom tracing points in the code, it can directly align with the OpenTelemetry standard. This is the recommended integration plan for APM. If an application is accessed through a non-OpenTelemetry scheme (such as the Skywalking scheme), APM will map the fields of other schemes to the OpenTelemetry link protocol standard based on link semantics.

Getting Link Data From the TencentCloud API

Application Performance Monitoring (APM) provides the DescribeGeneralOTSpanList TencentCloud API for obtaining link data.

Response Result Conversion

After calling the DescribeGeneralOTSpanList TencentCloud API, the response result is in the following JSON format text.
{
"Response":{
"RequestId":"f796c81b-d0c6-4cf7-b0fa-4d9194ecad10",
"Spans":"Base64EncodedString",
"TotalCount":11151
}
}
Among them, the Spans field contains all the link data. Since the data has been compressed, the result needs to be converted in the following three steps.
1. Decode the text in the Spans field using Base64 to obtain the compressed byte array.
2. Use gzip to decompress the compressed byte array and obtain the byte array before compression.
3. Use the UTF-8 character set to convert the byte array before compression into text.
Take Java language as an example. You can refer to the following code snippet to implement response result conversion.
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.zip.GZIPInputStream;

public class OtApiDecoder {
public static String decodeSpans(String spans) {
Base64.Decoder base64Decoder = Base64.getDecoder();
byte[] bytes = base64Decoder.decode(spans);
try (ByteArrayInputStream bais = new ByteArrayInputStream(bytes);
GZIPInputStream gis = new GZIPInputStream(bais);
ByteArrayOutputStream baos = new ByteArrayOutputStream();) {
byte[] buffer = new byte[1024];
int bytesRead = 0;
while ((bytesRead = gis.read(buffer)) != -1) {
baos.write(buffer, 0, bytesRead);
}
bytes = baos.toByteArray();
String result = new String(bytes, StandardCharsets.UTF_8);
return result;
} catch (IOException e) {
e.printStackTrace();
}
return null;
}
}
For other languages, there are also standard class libraries that can handle result conversion.

Link Data Structure

After the above conversion, the result is a JSON text. Its data structure follows the protocol format of the ptrace project. You can refer to the following example to understand the detailed content of the link data.
{
"resourceSpans":[
{
"resource":{
"attributes":[
{
"key":"service.name",
"value":{
"stringValue":"java-order-service"
}
}
]
},
"scopeSpans":[
{
"scope":{
"name":"apm/traces/spans",
"version":"v1.0"
},
"spans":[
{
"traceId":"9bda979bfbf9f27f94232909dc2a0a68",
"spanId":"e2f379eb4405dcb5",
"parentSpanId":"",
"name":"GET /slowSql",
"kind":2,
"startTimeUnixNano":"1741082699964148",
"endTimeUnixNano":"1741082703966151",
"attributes":[
{
"key":"key1",
"value":{
"stringValue":"value1"
}
},
{
"key":"key2",
"value":{
"stringValue":"value2"
}
}
],
"status":{
"code":0
}
}
]
}
]
}
]
}
Link data is a result set composed of multiple spans. In a JSON text, it is grouped by application name. Each group contains a list of spans belonging to that application, which is reflected by the spans field. The specific content of each Span follows the OpenTelemetry protocol standard. In the attribute set (reflected by the attributes field), APM has enhanced the following attributes based on the OpenTelemetry protocol standard:
Attribute
Description
service.instance
Represents the application instance that generated the Span, taken from the host.name field in Resource. When using Tencent Cloud enhanced Java probe for integration, or integrating in a TKE environment through tencent-opentelemetry-operator one-click integration, the probe will automatically include this information. For other integration schemes, add host.name to Resource when integrating applications. For details, see Custom Application Instance Attributes.
peer.service
Represents the peer service of this Span. If the calling role of the current Span is Server, APM will set this field to the application initiating the request; if the calling role of the current Span is Client, APM will set this field to the target application of the request.
status_code_xx
Represents the status code of this Span. APM integrates status codes of various protocols in this field, expressed in the form of protocol_status code, such as HTTP_404 or gRPC_0.
origin.operation
Represents the name of this Span. Since APM has the ability to automatically converge API names, the Span name saved in the name field may be modified. APM will save the original Span name in this field.
db.statement.excess
Represents the SQL statement of this Span, applicable to database request Spans. Since the SQL statement saved in the metric data has a length limit, the SQL statement saved in the db.query.text attribute may be truncated. APM will save the original SQL statement in this field.
component
Represents the event tracking component of this Span. Tencent Cloud Enhanced Java probes and some open-source OpenTelemetry probes will automatically include this information.
agent.version
Represents the version of the probe used for application access. The Tencent Cloud Enhanced Java probe will automatically include this information.

Custom Event Tracking Enhancement

If you perform custom event tracking enhancement through the OpenTelemetry API, please pay attention to the following important field information. If it is not specified during event tracking, some features of APM may become unavailable. Each programming language used in the OpenTelemetry API has a convenient way to specify this value.
General scenarios
Field Name
Description
Span Kind
All Spans must be specified, representing the type of Span, which is called the call role in APM. The value can be one of Server, Client, Producer, Consumer, Internal.
Represents the status of a Span. The value can be one of Ok, Error, Unset.
Represents the error type of a Span. When the status of a Span is Error, it is recommended to specify it. APM will aggregate and count error Spans based on the dimension of error type.
Represents the error information of a Span. It is recommended to specify it when the status of a Span is Error.
Database call
Field Name
Description
Represents the database type. This field must be specified in the attribute set (attributes) when the Span is a database call.
Represents the address of the database service. When the Span is a database call, it is recommended to specify this field in the attribute set (attributes).
Represents the port of the database service. It is recommended to specify this field in the attribute set (attributes) when the Span is a database call.
Represents the database name. When the Span is a database call, it is recommended to specify this field in the attribute set (attributes).
Represents the database query statement (SQL). This field must be specified in the attribute set (attributes) when the Span is a database call.






ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック