Telemetry Reference Page

Telemetry data types are crucial for understanding the performance, behavior, and health of applications and infrastructure. They can be broadly categorized into three main types: traces, metrics, and logs. Each serves a distinct purpose and provides valuable insights in different scenarios. Here are some examples of each type to illustrate their applications and utility:

1. Traces

Traces are used to track the journey of a request as it moves through various parts of an application or across multiple services. Each trace consists of multiple spans, where each span represents a single operation or task.

Examples:

• Web Application: A trace can show the path of a user’s request from hitting a web server, querying a database, calling an external API, and finally returning a response to the user.
• Microservices Architecture: Tracing can help visualize the entire workflow and interaction between microservices when processing a transaction or a request, identifying latency issues or failures in specific services.

Example Trace Log:

{
  "traceId": "abc123",
  "spanId": "def456",
  "parentId": "ghi789",
  "name": "http-request",
  "timestamp": "1657890123456",
  "duration": "250ms",
  "attributes": {
    "http.method": "GET",
    "http.url": "https://api.example.com/data",
    "http.status_code": "200"
  },
  "events": [
    {
      "time": "1657890123456",
      "name": "db-query-start"
    },
    {
      "time": "1657890123706",
      "name": "db-query-end"
    }
  ]
}

2. Metrics

Metrics are quantitative data that measure various aspects of system performance and resource usage. They are often collected at regular intervals and are used for real-time monitoring and historical analysis.

Examples:

• System Metrics: CPU usage, memory usage, disk I/O, network traffic. These metrics are critical for monitoring the health and performance of servers and identifying potential bottlenecks.
• Application Metrics: Response times, error rates, throughput (requests per second), and queue lengths. These metrics help developers and operators gauge the performance and efficiency of their applications.

Example Metric Log:

{
  "metric": "cpu_usage",
  "timestamp": "1657890123456",
  "value": 85.5,
  "tags": {
    "host": "server01",
    "region": "us-east-1"
  }
}

Example of time-series Metric

{
  "metric": "http_requests",
  "interval": "1min",
  "values": [
    {"timestamp": "1657890120000", "count": 320},
    {"timestamp": "1657890180000", "count": 280}
  ],
  "tags": {
    "status": "200",
    "endpoint": "/api/data"
  }
}

3. Logs

Logs provide descriptive records of events, errors, or status changes within an application or system. They are typically generated in a text format and can provide context-rich information surrounding events or errors.

Examples:

• Error Logs: Detailed descriptions of errors, including timestamps, error messages, and stack traces. Useful for debugging and identifying what went wrong in an application.
• Audit Logs: Records of actions taken by users, such as logins, data access, and modifications. These are crucial for security auditing and compliance monitoring.
• Event Logs: General logs of events that occur within an application, such as user actions, system updates, or configuration changes. They help in understanding the sequence of actions leading up to an event or issue.

Example Simple Log Entry:

2023-05-01 12:00:01.123 INFO User login successful - userID: 12345

Example Structured Log Entry:

{
  "level": "ERROR",
  "timestamp": "1657890123456",
  "message": "Failed to connect to database",
  "error": {
    "type": "ConnectionTimeout",
    "message": "Timed out after 3000 ms"
  },
  "context": {
    "service": "user-service",
    "trace_id": "abc123",
    "span_id": "def456"
  }
}