Skip to content

11_telemetry_profiles_.md

Latest commit

 

History

History
233 lines (170 loc) · 8.19 KB

11_telemetry_profiles_.md

File metadata and controls

233 lines (170 loc) · 8.19 KB

Chapter 11: Telemetry Profiles

In the previous chapter, Device Configuration Management, we explored how device configurations such as log upload and telemetry settings are dynamically generated based on device context and rules evaluation. Now, we focus on Telemetry Profiles, an abstraction that manages telemetry configurations and profiles, including the retrieval and evaluation of telemetry rules. This chapter will guide you to understand how telemetry profiles work and how to use them effectively.

11.1 Motivation

Telemetry Profiles allow xconfwebconfig to define and manage how telemetry data is collected, processed, and reported for devices. These profiles play a crucial role in ensuring that devices send their telemetry data in a structured and predictable manner. Telemetry Profiles must be tailored to match the device’s context, such as its model, environment, or application type.

Central Use Case

Imagine a scenario where a set-top box (STB) requests its telemetry configuration. The telemetry profile must specify:

  1. Collection Frequency: How often telemetry data should be collected.
  2. Telemetry Parameters: What data should be included in the report, such as logs or metrics.
  3. Upload Protocol and Repository: Where and how the telemetry data should be uploaded.

This configuration needs to be dynamically generated based on the device’s context, ensuring that telemetry profiles are optimized for specific environments (e.g., DEV, PROD) and device models.

11.2 Key Concepts

11.2.1 Telemetry Profile

A Telemetry Profile is a structured configuration that defines how telemetry data is collected and reported. It includes:

  • Schedule: Specifies when telemetry data should be collected and uploaded (e.g., every 15 minutes).
  • Parameters: Defines the specific telemetry data to be collected (e.g., logs, events, metrics).
  • Upload Settings: Specifies the repository URL and protocol used to upload telemetry data.

Example Telemetry Profile:

{
    "id": "profile_123",
    "name": "Telemetry Profile for PROD",
    "schedule": "*/15 * * * *",
    "uploadRepository": "https://telemetry-repo.example.com",
    "uploadProtocol": "HTTP"
}

11.2.2 Telemetry Rules

Telemetry Rules are logical conditions used to determine which telemetry profile applies to a device. These rules are evaluated using the device’s context and may include:

  • Conditions: Checks such as model = MODEL_XYZ or env = PROD.
  • Actions: Specifies the telemetry profile to associate with the rule.

Example Telemetry Rule:

{
    "id": "rule_123",
    "name": "Telemetry Rule for MODEL_XYZ",
    "condition": {
        "freeArg": {
            "type": "STRING",
            "name": "model"
        },
        "operation": "IS",
        "fixedArg": {
            "value": "MODEL_XYZ"
        }
    },
    "boundTelemetryId": "profile_123"
}

11.2.3 Temporary vs. Permanent Profiles

Telemetry Profiles can be categorized into:

  • Temporary Profiles: Created dynamically based on specific conditions and are valid for a limited duration.
  • Permanent Profiles: Predefined profiles stored in the database and applied based on rules.

11.3 Using Telemetry Profiles

Step 1: Fetching Telemetry Profiles

To fetch the telemetry profile for a specific device context, use the GetTelemetryForContext method. This method evaluates the context map and retrieves the matching profile.

Example Code:

context := map[string]string{
    "model": "MODEL_XYZ",
    "env": "PROD",
    "applicationType": "STB",
}

telemetryProfileService := telemetry.NewTelemetryProfileService()
telemetryProfile := telemetryProfileService.GetTelemetryForContext(context)

Explanation:

  • Input: The context map contains information about the device (e.g., model, env).
  • Output: The telemetryProfile object contains the telemetry configuration for the device.

Step 2: Handling the Telemetry Profile

Once the telemetry profile is retrieved, it can be used to configure the device.

Example Code:

if telemetryProfile != nil {
    fmt.Printf("Telemetry Profile ID: %s\n", telemetryProfile.ID)
    fmt.Printf("Schedule: %s\n", telemetryProfile.Schedule)
    fmt.Printf("Repository URL: %s\n", telemetryProfile.UploadRepository)
} else {
    fmt.Println("No matching telemetry profile found.")
}

Explanation:

  • If a profile is found, its details are printed.
  • If no profile matches the context, the output informs the user.

Step 3: Creating Temporary Profiles

Temporary telemetry profiles can be dynamically created based on specific conditions.

Example Code:

telemetryProfile := logupload.TelemetryProfile{
    ID:               "temp_profile_001",
    Name:             "Temporary Profile",
    Schedule:         "*/30 * * * *",
    UploadRepository: "https://temp-repo.example.com",
    UploadProtocol:   "HTTP",
}

telemetryProfileService.CreateTelemetryProfile("model", "MODEL_XYZ", telemetryProfile)

Explanation:

  • Input: A telemetry profile is created for devices where model = MODEL_XYZ.
  • Action: The profile is stored temporarily and can be retrieved later.

11.4 Internal Implementation

Sequence Diagram: Telemetry Profile Evaluation

The workflow for fetching telemetry profiles based on device context is illustrated below:

sequenceDiagram
participant Device as Device Context
participant Service as Telemetry Profile Service
participant Rules as Telemetry Rules Engine
participant DB as Database

Device->>Service: Request telemetry profile
Service->>Rules: Evaluate context map
Rules->>DB: Fetch telemetry rules and profiles
DB-->>Rules: Return matching rules and profiles
Rules-->>Service: Return telemetry profile
Service-->>Device: Respond with telemetry profile
Loading

Code Walkthrough: Key Functions

1. Fetching Profiles

The GetTelemetryForContext method retrieves the telemetry profile for a given context.

File: dataapi/dcm/telemetry/telemetry_profile.go

func (t *TelemetryProfileService) GetTelemetryForContext(context map[string]string) *logupload.TelemetryProfile {
    telemetryProfile := t.GetTemporaryProfileForContext(context)
    return telemetryProfile
}

Explanation:

  • First checks for a temporary profile matching the context.
  • Returns the profile if found, otherwise returns nil.

2. Evaluating Rules

The ProcessTelemetryTwoRules method evaluates telemetry rules to determine applicable profiles.

File: dataapi/dcm/telemetry/telemetry_profile.go

func (t *TelemetryProfileService) ProcessTelemetryTwoRules(context map[string]string) []*logupload.TelemetryTwoRule {
    all := logupload.GetTelemetryTwoRuleList()
    ruleProcessorFactory := re.NewRuleProcessorFactory()
    processor := ruleProcessorFactory.Processor
    matched := []*logupload.TelemetryTwoRule{}
    for _, tRule := range all {
        if processor.Evaluate(&tRule.Rule, context, log.Fields{}) {
            matched = append(matched, tRule)
        }
    }
    return matched
}

Explanation:

  • Fetches all telemetry rules from the database.
  • Evaluates each rule against the context map.
  • Returns the matched rules.

11.5 Best Practices

  1. Define Clear Telemetry Profiles: Ensure profiles are well-structured and meet the operational requirements of the environment.
  2. Use Temporary Profiles Judiciously: Create temporary profiles for specific conditions and ensure they expire after their intended use.
  3. Log Rule Evaluations: Use detailed logs to track rule evaluation and debugging.

Summary

In this chapter, we explored Telemetry Profiles, an essential abstraction for managing telemetry configurations and profiles in xconfwebconfig. You learned how telemetry profiles are created, evaluated, and applied based on device context. This abstraction ensures devices are configured with optimal telemetry settings tailored to their environment.

Next, we will explore the Tagging System and its role in categorizing and managing devices.

Generated by AI Codebase Knowledge Builder