telemetry-foundations

Defines OpenTelemetry-aligned naming conventions for traces, metrics, logs, and PII redaction.

1.4k|284|Updated Nov 2, 2025
One-click install
npx skills add https://github.com/microsoft/hve-core --skill telemetry-foundations
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: telemetry-foundations
Source: https://github.com/microsoft/hve-core/tree/main/.github/skills/shared/telemetry-foundations
Command: npx skills add https://github.com/microsoft/hve-core --skill telemetry-foundations

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Teams producing observability instrumentation often end up with inconsistent span names, unbounded metric cardinality, and accidental PII leakage across services. This Skill provides a shared, declarative telemetry vocabulary so agents and developers emit traces, metrics, and logs that follow one OpenTelemetry-aligned standard.

Core Features & Use Cases

  • Trace, Metric, and Log Vocabulary: Standardized span kinds, span naming patterns (<verb>.<resource>), metric instrument types with UCUM units, and OTel log severity levels with trace correlation fields.
  • PII Denylist with Redaction Strategies: A default-deny list of sensitive fields (emails, tokens, payment data) with hash, drop, and tokenize redaction patterns.
  • Sampling and Cardinality Guidance: Parent-based and tail-based sampling defaults plus cardinality discipline to control telemetry cost.
  • Use Case: When writing an ADR or code-review report that touches observability, apply this vocabulary so every service names spans like get.order and metrics like http.server.request.duration consistently, and never emits raw user emails as attributes.

Quick Start

Ask the agent to apply the telemetry-foundations conventions when instrumenting a new service endpoint with spans, metrics, and structured logs.

Frequently Asked Questions about telemetry-foundations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I name OpenTelemetry spans and metrics consistently?

Name spans with the pattern `<verb>.<resource>` in lowercase dot-separated tokens, such as `get.order` or `publish.order.created`. Name metrics as `<domain>.<entity>.<measure>`, like `http.server.request.duration`, and prefer official OTel semantic conventions where they exist.

How should PII be handled in telemetry data?

Treat PII as default-deny using the denylist in references/pii-denylist.md. Apply a redaction strategy before emitting: hash fields that must remain joinable (SHA-256), drop credentials and payment data entirely, or tokenize values resolvable only through an access-controlled store.

Does this vocabulary require a specific observability vendor or SDK?

No, the vocabulary is declarative and vendor-agnostic. It defines names and shapes aligned with the OpenTelemetry data model and assumes OTLP as the wire protocol, leaving the choice of SDK, exporter, and backend to the implementing team.

How do I prevent high metric cardinality in OpenTelemetry?

Bound high-cardinality dimensions like user IDs and request IDs at the source, or move them to trace exemplars and log attributes instead of metric dimensions. Every attribute on a metric multiplies the time-series count, so keep dimensions bounded.

What sampling strategy should I use for distributed traces?

Use a parent-based sampler by default so child spans inherit the sampling decision and traces remain whole. Where tail-based sampling is available in a collector, bias policies toward keeping error traces and a representative sample of successful traces.