capability-telemetry

name	capability-telemetry
description	Covers observability integration including metrics, traces, and logs following OpenTelemetry conventions. Use when instrumenting services for monitoring and debugging.

Capability: Telemetry

This skill covers telemetry integration for Datum Cloud services.

Overview

Telemetry enables services to emit observability data. The telemetry system handles:

• Metrics (numeric measurements over time)
• Traces (distributed request tracking)
• Logs (structured event records)

All telemetry follows OpenTelemetry conventions.

Core Concepts

Metrics

Numeric measurements with dimensions:

// Counter - monotonically increasing
requests := meter.Int64Counter("myresource.requests.total")
requests.Add(ctx, 1, attribute.String("method", "create"))

// Gauge - point-in-time value
activeResources := meter.Int64UpDownCounter("myresource.active")
activeResources.Add(ctx, 1)

// Histogram - distribution of values
latency := meter.Float64Histogram("myresource.request.duration_seconds")
latency.Record(ctx, duration.Seconds())

Traces

Request flow across services:

ctx, span := tracer.Start(ctx, "CreateMyResource")
defer span.End()

span.SetAttributes(
    attribute.String("resource.name", name),
    attribute.String("resource.namespace", namespace),
)

if err != nil {
    span.RecordError(err)
    span.SetStatus(codes.Error, err.Error())
}

Logs

Structured event records:

logger.Info("resource created",
    "name", resource.Name,
    "namespace", resource.Namespace,
    "spec", resource.Spec,
)

logger.Error(err, "failed to create resource",
    "name", name,
)

Naming Conventions

Metric Names

Pattern: {service}.{resource}.{measurement}[.{unit}]

Example	Description
compute.vm.requests.total	Total VM API requests
compute.vm.active	Currently active VMs
compute.vm.cpu.utilization.percent	VM CPU utilization
compute.vm.request.duration.seconds	Request latency

Span Names

Pattern: {Operation}{Resource}

Example	Description
CreateVirtualMachine	Creating a VM
ReconcileVirtualMachine	Reconciling a VM
ValidateVirtualMachine	Validating a VM

Log Fields

Standard fields:

• resource.name — Resource name
• resource.namespace — Resource namespace
• resource.apiVersion — API version
• resource.kind — Resource kind
• operation — What was attempted
• error — Error if failed

Implementation

Read implementation.md for:

• Setting up telemetry providers
• Instrumenting API handlers
• Adding custom metrics
• Trace context propagation

Validation

Run scripts/validate-metrics.sh to verify:

• Metrics are registered
• Traces are emitted
• Naming conventions followed

Related Files

• implementation.md — Integration guide
• scripts/validate-metrics.sh — Validation script
• scripts/scaffold-telemetry.sh — Scaffolding script