Skip to main content

​
1. Purpose

This document defines the normative behavior and usage requirements for Yourouter Data Tracing. The goal is to enable auditing, reconciliation, and troubleshooting by querying Tencent Cloud Application Performance Management (APM) for an end-to-end distributed trace of a single request, using a trace identifier returned by Yourouter.

​
2. Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 (to express requirement levels).
  • Trace ID: A unique identifier used to retrieve a distributed trace in Tencent Cloud APM.
  • APM: Tencent Cloud Application Performance Management.
  • Client: Any caller of the Yourouter API (service, SDK, script, etc.).
  • Trace Retention Window: The time window during which a Trace is searchable in APM. In this specification, it is 72 hours (3 days).

​
3. Protocol

This specification does not mandate transport implementation details beyond requiring that the Trace ID be conveyed via an HTTP response header.

​
4. Trace ID Response Requirements

​
4.1 Header Definition

Yourouter MUST return the following response header on every successful API response:
  • Header Name: X-Yourouter-Trace-Id
  • Header Value: <trace_id> (a non-empty string identifying the trace for this request)
Note: This specification does not define the Trace ID format, length, encoding, or ordering properties.

​
4.2 Absence Handling

  • If Yourouter cannot generate or report a trace due to factors outside of its control, it MAY omit the header.
  • If the X-Yourouter-Trace-Id header is absent, the Client MUST treat the request as non-traceable, and MUST NOT rely on Tencent Cloud APM for trace-based validation of that request.

​
5. Retention

​
5.1 Retention Window

Trace data in Tencent Cloud APM is retained and searchable for 72 hours (3 days). After the retention window ends, the trace SHALL be considered non-searchable or unavailable.

​
5.2 Time-Bound Requirements

Any audit, reconciliation, evidence collection, or troubleshooting that depends on APM trace data MUST be completed within 72 hours of the request time. After 72 hours, users MUST NOT interpret an inability to locate the trace as evidence of a system malfunction or data inconsistency.

​
6. Client Persistence Requirements

​
6.1 Immediate Persistence (Required)

Upon receiving a response, the Client MUST immediately extract and persist the value of X-Yourouter-Trace-Id. Persistence targets MAY include (but are not limited to): application logs, structured logging pipelines, databases, ticketing systems, alert payloads, or observability platforms’ custom fields.

​
6.2 Minimum Correlation Set

The Client SHOULD persist the following fields alongside the Trace ID to enable reliable correlation:
  • Client-side request identifier (e.g., internal request id)
  • Request timestamp (at least second-level precision)
  • Yourouter API path or operation
  • HTTP status code (or equivalent success/failure indicator)

​
7. APM Query Procedure

​
7.1 Required Procedure

Within the retention window, users MUST follow this procedure to retrieve the trace:
  1. Obtain the X-Yourouter-Trace-Id value from the response headers.
  2. Open the Tencent Cloud APM Console.
  3. Navigate to Trace Search / Distributed Tracing (menu names may vary by APM version).
  4. Search using the Trace ID and open the trace detail view.
  5. Review end-to-end latency, dependency graph, errors/retries, and outbound calls from Yourouter to upstream services.

​
7.2 Query Failure Handling

If the trace cannot be found within 72 hours, users SHOULD first verify:
  • The Trace ID was copied correctly (no truncation/whitespace)
  • APM sampling settings (some requests may not produce traces)
  • The selected time range includes the request timestamp
If these are confirmed and the trace still cannot be found, users MAY provide the Trace ID and request metadata to Yourouter support for further investigation.

​
8. Attribution and Validation

​
8.1 Attribution Principle

In the trace detail view, users SHALL use Yourouter’s outbound calls to upstream services as the primary validation evidence, including:
  • Destination Host / Endpoint / URL (to validate routing destination)
  • Latency, status codes, and error details (to validate request outcome and behavior)

​
8.2 Non-Goals

This specification MUST NOT require or assume any stable span tag names, attribute keys, or internal labeling conventions. Implementations and documentation SHOULD NOT depend on fixed tag names as a public interface.

​
9. Security and Privacy

Clients SHOULD avoid logging sensitive request payloads (e.g., prompts, personal data). Clients SHOULD store only the Trace ID and the minimum required correlation metadata to meet audit and troubleshooting needs.

​
10. Conformance

An implementation is considered conformant with this specification if:
  • Yourouter returns X-Yourouter-Trace-Id on successful responses (Section 4.1).
  • The retention window is documented and enforced as 72 hours (Section 5).
  • The documentation requires Clients to immediately persist the Trace ID and provides the mandatory query procedure (Sections 6 and 7).