/wiztelemetry-tracing

name: wiztelemetry-tracing
description: Use when working with WizTelemetry Tracing extension for KubeSphere, including installation, configuration, and tracing query API

WizTelemetry Tracing

Overview

WizTelemetry Tracing is an extension component in the KubeSphere Observability Platform that provides distributed tracing functionality based on the [OpenTelemetry](https://opentelemetry.io/docs/specs/otel/trace/) standard.

When to Use

• Installing or configuring the WizTelemetry Tracing extension
• Understanding tracing architecture (Generator + Operator + Collector + Agent)
• Using the tracing query API to query traces, spans, service graphs
• Configuring OpenTelemetry auto-instrumentation for applications

Components

| Component | Description | Default Enabled | |-----------|-------------|-----------------| | generator | WizTelemetry Tracing Generator: generates service graphs from tracing data (StatefulSet) | true | | operator | OpenTelemetry Operator: manages OpenTelemetry Collector and auto-instrumentation | true | | collector | OpenTelemetry Collector for WizTelemetry: receives traces, exports to Vector and OpenSearch | true | | agent | WizTelemetry Tracing Agent: collects tracing data from local log files (DaemonSet) | false | | demo | OpenTelemetry Demo: generates sample tracing data for demonstration | false |

Dependencies

• **WizTelemetry Platform Service** (whizard-telemetry): Required
• **OpenSearch** (opensearch): Required

Installation

Prerequisites

**REQUIRED: Complete all steps in order before generating InstallPlan.**

Step 1: Get Available Clusters and Confirm Target

**CRITICAL: DO NOT proceed until target clusters are determined.**

**Step 1.1: Get available clusters**

kubectl get clusters -o jsonpath='{.items[*].metadata.name}'

**Step 1.2: Determine target clusters**

• If user **explicitly specified** target clusters in the request -> Use those clusters directly, proceed to Step 2
• If user **did NOT specify** target clusters -> Ask user to confirm which clusters to deploy to, then proceed to Step 2

**Ask user (if not specified):**

Available clusters: host, dev
Which clusters do you want to deploy WizTelemetry Tracing to?

Step 2: Get Latest Version (if not provided by user)

**MUST do this to get the latest version:**

kubectl get extensionversions -n kubesphere-system -l kubesphere.io/extension-ref=wiztelemetry-tracing -o jsonpath='{range .items[*]}{.spec.version}{"\n"}{end}' | sort -V | tail -1

This outputs the latest version (e.g., `1.0.6`). Note this down - you'll use it in the InstallPlan.

Step 3: Get Generator Endpoint

**Get a node IP from the target cluster:**

kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}' 2>/dev/null || \
kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}'

This outputs a node IP (e.g., `192.168.1.100`). Use this as the generator endpoint.

**If multiple shards (e.g., `generator.shardCount: 3`), generate all endpoints:**

NODE_IP="<NODE_IP>"
for i in 0 1 2; do
  PORT=$((32318 + i))
  echo "  - http://${NODE_IP}:${PORT}"
done

Replace `<NODE_IP>` with the actual node IP from the previous command.

Step 4: Confirm Configuration with User

Before creating the InstallPlan, confirm the following with the user:

I'll install WizTelemetry Tracing with the following configuration:
- Version: <VERSION>
- Target clusters: <TARGET_CLUSTERS>
- Generator endpoint: http://<NODE_IP>:32318
- OpenSearch endpoint: <OPENSEARCH_ENDPOINT>

Do you want to proceed? (yes/no)

If user confirms, proceed to create the InstallPlan. If not, adjust the configuration based on user feedback.

Step 5: Create InstallPlan

**CRITICAL: InstallPlan `metadata.name` MUST be `wiztelemetry-tracing`. DO NOT use any other name.**

**CRITICAL: `config` field is YAML format. You MUST:**

• Use the config structure exactly as shown in the template
• **DO NOT** add configuration fields that are not shown in the template
• **DO NOT** modify the structure or hierarchy

**CRITICAL: All placeholders MUST be replaced with actual values. DO NOT leave them as placeholders.**

**Based on your selections:**

• **Target clusters**: User-confirmed cluster names
• **OpenSearch endpoint**: User-provided (default: `https://opensearch-cluster-data.kubesphere-logging-system.svc:9200`)
• **OpenSearch credentials**: User-provided (default user: `admin`)

Template

apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: wiztelemetry-tracing
  namespace: kubesphere-system
spec:
  extension:
    name: wiztelemetry-tracing
    version: <VERSION>  # From Step 2
  enabled: true
  upgradeStrategy: Manual
  config: |
    global:
      generator:
        endpoints:
          - http://<HOST_NODE_IP>:32318
      storage:
        opensearch:
          auth:
            strategy: basic
            user: <OPENSEARCH_USER>
            password: <OPENSEARCH_PASSWORD>
          endpoints:
            - <OPENSEARCH_ENDPOINT>
    generator:
      shardCount: 1
      service:
        nodePort: 32318
  clusterScheduling:
    placement:
      clusters:
        - <TARGET_CLUSTERS>

**Replace placeholders:**

• `<VERSION>`: From Step 2 (e.g., `1.0.6`)
• `<HOST_NODE_IP>`: Node IP from Step 3 (e.g., `192.168.1.100`)
• `<OPENSEARCH_USER>`: OpenSearch username
• `<OPENSEARCH_PASSWORD>`: OpenSearch password
• `<OPENSEARCH_ENDPOINT>`: OpenSearch endpoint (e.g., `https://opensearch-cluster-data.kubesphere-logging-system.svc:9200`)
• `<TARGET_CLUSTERS>`: User-confirmed cluster names

Enable Agent (Log File Collection)

To enable tracing data collection from local log files, set `agent.enabled: true` in the config. This deploys a DaemonSet that scans log files and forwards traces to the generator.

Enable Demo

To enable the OpenTelemetry Demo (generates sample trace data), set `demo