К основному содержанию
скилл CX Codex

telemetry-foundations — скилл для Claude Code

Скилл telemetry-foundations задаёт декларативный словарь OpenTelemetry для логов, спанов и метрик, а также правила очистки персональных данных (PII) при генерации кода и проектной документации.

MIT ★ 1 627 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add microsoft/hve-core --skill telemetry-foundations -a claude-code
Открыть на GitHub

Что делает telemetry-foundations

Скилл описывает правила разметки телеметрии без привязки к конкретным SDK или вендорам. В качестве протокола передачи предполагается OTLP, а спаны, метрики и логи строятся по моделям OpenTelemetry. На каждом спане требуются три атрибута ресурса: service.name, service.version и deployment.environment.

Имена спанов формируются по схеме <действие>.<ресурс> (например, get.order), если для домена нет готовых семантических конвенций OTel. Метрики именуются как <домен>.<сущность>.<величина>, а длительности измеряются гистограммами в секундах по шкале UCUM. Для защиты данных действует принцип запрета по умолчанию: любые атрибуты из denylist PII нельзя отправлять без явного хеширования, удаления или токенизации.

Если в метрики попадают динамические идентификаторы пользователей или сырые строки, кардинальность временных рядов быстро выйдет из-под контроля, поэтому такие значения выносят в трейсы или экземпляры.

Какие задачи решает

  • стандартизировать именование спанов и метрик по правилам OpenTelemetry
  • предотвратить утечку персональных данных через трейсы и логи
  • ограничить кардинальность метрик в микросервисах
  • составить требования к наблюдаемости для ADR и отчётов код-ревью

Примеры запросов агенту

  • Оформи спаны и метрики для сервиса заказов по правилам telemetry-foundations.
  • Проверь код логирования на утечки PII и настрой хеширование поля user.id.
  • Составь раздел телеметрии для ADR с именами метрик и родительским сэмплированием.

Как установить telemetry-foundations

1Через Skills CLI (Vercel)

npx skills add microsoft/hve-core --skill telemetry-foundations -a claude-code

2Вручную: положить файлы

~/.claude/skills/telemetry-foundations/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/telemetry-foundations/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о telemetry-foundations

Как установить telemetry-foundations в Claude Code?

Выполните команду npx skills add microsoft/hve-core --skill telemetry-foundations -a claude-code.

Что делает скилл telemetry-foundations?

Он задаёт правила именования спанов, метрик и логов в соответствии со стандартами OpenTelemetry, а также определяет способы маскирования конфиденциальных данных.

Как в telemetry-foundations устроена защита персональных данных?

Действует правило default-deny на основе списка запрещённых полей. Данные PII либо удаляются из телеметрии, либо хешируются алгоритмом SHA-256, либо заменяются токеном.

Исходный текст

SKILL.md · MIT
---
name: telemetry-foundations
description: 'Declarative OpenTelemetry-aligned telemetry vocabulary and instrumentation conventions for traces, metrics, logs, and PII handling'
---

# Telemetry Foundations

## Overview

A shared vocabulary for observability across HVE Core agents. This skill describes *what* telemetry data exists and *how it is named*, not which SDK or vendor to use. Agents producing planning artifacts (ADRs, PRDs, security/RAI plans, code-review reports) and agents producing user-facing application code reference this skill so that downstream pipelines (traces, metrics, logs) speak a consistent OpenTelemetry-aligned language.

## When to Apply

Apply this skill in the following situations:

* Any agent producing user-facing application code that emits spans, metrics, or structured logs.
* Architecture Decision Records that touch observability, monitoring, or audit logging.
* Code-review reports that flag telemetry gaps, inconsistent span naming, or unbounded metric cardinality.
* Security or Responsible AI plans that cite audit logs, traceability, or evidence chains.
* Product or business requirement documents that specify success metrics expressed as service telemetry.

## Core Principles

The vocabulary in this skill follows five principles:

* Declarative, not prescriptive. Define the names and shapes; leave the choice of SDK, exporter, and backend to the implementing team.
* OpenTelemetry-aligned. Trace, metric, and log models follow the OTel data model so artifacts remain portable.
* Semantic conventions first. Where an OTel semantic convention exists for a domain (HTTP, RPC, database, messaging, GenAI, FaaS), prefer it over a bespoke attribute.
* PII by denylist. Treat PII as default-deny via the denylist in [references/pii-denylist.md](references/pii-denylist.md); any field listed there requires an explicit redaction strategy before it can be emitted.
* Vendor-agnostic. Avoid coupling vocabulary to a single backend; OTLP is the assumed wire protocol.

## Trace Vocabulary

Spans describe a unit of work and its causal relationship to other work.

Span kinds:

* `server` - inbound request handled by this service.
* `client` - outbound request issued by this service.
* `producer` - asynchronous message published to a queue or topic.
* `consumer` - asynchronous message received from a queue or topic.
* `internal` - in-process operation with no remote peer.

Required resource-scoped attributes on every span:

* `service.name`
* `service.version`
* `deployment.environment`

Span naming pattern: `<verb>.<resource>` using lowercase dot-separated tokens. The verb describes the operation (`get`, `create`, `publish`, `consume`, `query`); the resource describes the target entity (`order`, `customer`, `payment.intent`). Examples: `get.order`, `publish.order.created`, `query.customer.by_email`.

For domains covered by OTel semantic conventions (HTTP, RPC, database, messaging, GenAI, FaaS), use the convention's span-naming guidance instead of the generic pattern above.

## Metric Vocabulary

Metrics describe aggregate measurements over time.

Instrument types:

* `counter` - monotonic, additive (request count, bytes sent).
* `up-down-counter` - non-monotonic, additive (queue depth, active connections).
* `histogram` - distribution of values (request duration, payload size).
* `gauge` - last-sampled value, non-additive (CPU temperature, memory in use).
* `observable-counter`, `observable-up-down-counter`, `observable-gauge` - async variants polled by the SDK.

Unit conventions follow [UCUM](https://ucum.org/ucum). Examples: `s` (seconds), `ms` (milliseconds), `By` (bytes), `1` (dimensionless count). Express durations as histograms in seconds (`s`) by default to align with OTel HTTP semantic conventions.

Metric naming pattern: `<domain>.<entity>.<measure>` using lowercase dot-separated tokens. Examples: `http.server.request.duration`, `db.client.connections.usage`, `messaging.publish.duration`.

Cardinality discipline: every attribute attached to a metric multiplies the time-series count. Bound high-cardinality dimensions (user ID, request ID, free-form strings) at the source or move them to exemplars and traces.

## Log Vocabulary

Structured logs carry discrete events with severity and context.

Severity levels (OTel log data model):

* `TRACE` - fine-grained diagnostic detail, off by default.
* `DEBUG` - diagnostic detail useful during development.
* `INFO` - normal operational events.
* `WARN` - unexpected condition that does not block the operation.
* `ERROR` - operation failed; the caller likely saw a failure.
* `FATAL` - process is going to terminate.

Recommended structured fields on every log record:

* `timestamp` (ISO-8601, UTC).
* `severity_text` and `severity_number`.
* `body` (the human-readable message; structured data goes in `attributes`).
* `attributes.*` (typed key-value pairs scoped to this event).
* `resource.*` (inherited from the producing service).

Trace correlation: when a log record is emitted within an active span, inject `trace_id` and `span_id` so traces and logs join cleanly downstream. Logging libraries that integrate with the OTel context propagator do this automatically.

## PII Handling

Personally Identifiable Information is handled by denylist. The authoritative list lives in [references/pii-denylist.md](references/pii-denylist.md). Treat any field on that list as default-deny: do not emit it as a span attribute, metric dimension, or log field without an explicit redaction strategy.

Redaction patterns:

* Hash - one-way hash (SHA-256, optionally truncated) for fields that must remain joinable across events but should not be human-readable.
* Drop - omit the field entirely from telemetry.
* Tokenize - replace with an opaque token resolvable only through a separate, access-controlled store.

Identifier convention: where a stable user reference is needed in telemetry, use `user.id` populated with an opaque hash of the canonical user identifier, never the raw email, phone, or external account ID.

When introducing a new attribute that could contain PII, add it to the denylist first and choose a redaction strategy before emitting it.

## Sampling and Cost

Sampling controls the volume of telemetry shipped to downstream collectors.

Sampling strategies:

* Head-based - decision made at span start, propagated through the trace. Low cost, simple, but cannot bias toward late-discovered properties (such as errors).
* Tail-based - decision made after a trace completes, typically in a collector. Higher cost, allows policies such as "keep all error traces" and "keep slow traces".

Defaults:

* Use a parent-based sampler so child spans inherit the parent's sampling decision and traces remain whole.
* When tail-based sampling is available, bias toward keeping error traces and a representative sample of successful traces.

Metric and log sampling: metrics are pre-aggregated and rarely sampled; logs are typically rate-limited per severity rather than sampled.

## Resource Attributes

Resource attributes describe the entity producing the telemetry and are attached to every span, metric, and log record automatically by the SDK.

Required:

* `service.name`
* `service.version`
* `deployment.environment`
* `telemetry.sdk.name`
* `telemetry.sdk.language`
* `telemetry.sdk.version`

Recommended when applicable:

* `cloud.*` (cloud provider, region, account ID).
* `k8s.*` (cluster name, namespace, pod name).
* `host.*` (hostname, architecture, OS type).

Follow the OTel [Resource Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/resource/) for canonical attribute names.

## Decision Tree

Use this quick-select when choosing whether and how to instrument:

1. Is this user-facing or part of a user-visible flow? If no, prefer DEBUG logs and skip span/metric emission unless needed for capacity planning.
2. Is the cardinality of the proposed attributes bounded? If no, move the unbounded field to a log attribute or trace exemplar rather than a metric dimension.
3. Does the data contain or derive from a field in [references/pii-denylist.md](references/pii-denylist.md)? If yes, apply a redaction strategy before emitting.
4. Does the operation cross a service boundary (network, queue, process)? If yes, emit a span with the matching `server`, `client`, `producer`, or `consumer` kind and propagate context.
5. Is the operation high-volume? If yes, rely on parent-based sampling and (where available) tail-based policies; do not disable instrumentation outright.
6. Does an OpenTelemetry semantic convention cover this domain? If yes, use its attribute names and span-naming guidance; if no, follow the naming patterns in this skill and propose a new entry in [references/proposed-additions.md](references/proposed-additions.md).

## References

Authoritative external sources:

* [OpenTelemetry Semantic Conventions v1.41.0](https://opentelemetry.io/docs/specs/semconv/)
* [W3C Trace Context](https://www.w3.org/TR/trace-context/)
* [OpenTelemetry Protocol (OTLP) Specification](https://opentelemetry.io/docs/specs/otlp/)
* [OpenTelemetry Logs Data Model](https://opentelemetry.io/docs/specs/otel/logs/data-model/)
* [OpenTelemetry FaaS Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/faas/)

Portions adapted from OpenTelemetry Semantic Conventions, (C) OpenTelemetry Authors, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

Internal:

* [references/pii-denylist.md](references/pii-denylist.md) - authoritative PII denylist with redaction strategies.
* [references/proposed-additions.md](references/proposed-additions.md) - intake for new vocabulary proposals.

© microsoft · MIT · microsoft/hve-core

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
otel-telemetry-emissions ollygarden Скилл otel-telemetry-emissions для Claude Code сверяет телеметрию OpenTelemetry по версиям компонентов. Помогает проверить спаны, метрики, логи и атрибуты перед обновлением SDK или коллектора. CX Codex +1 ★ 126звёзд репо otel-instrumentation dash0 Скилл otel-instrumentation помогает агенту расставить спаны, метрики и логи OpenTelemetry так, чтобы телеметрия отвечала на вопросы, а не жгла бюджет. CX Codex +1 1 100установок observability-guidelines Mindrally Скилл observability-guidelines учит агента внедрять OpenTelemetry, трассировку и структурированные логи в распределённые сервисы. Пригодится при настройке мониторинга и метрик. CX Codex +1 826установок logging-observability curiositech Скилл logging-observability настраивает структурированное логирование, сквозную трассировку через OpenTelemetry и пороги алертов. Помогает связать логи сервисов и убрать лишний шум из оповещений. CX Codex +1 152установок monitoring-observability travisjneuman Скилл monitoring-observability помогает внедрить OpenTelemetry, структурированные логи и трейсинг в микросервисах. Он пригодится при настройке алертов по SLO и отладке распределённых систем. CX Codex +1 146установок Observability taste f Промпт Observability taste для ChatGPT задаёт правила инструментирования и мониторинга сервисов. Он помогает спроектировать логи, метрики, трассировки и оповещения. GP ChatGPT ★ 178 201звёзд репо

Из того же набора148

Весь набор →
adr-byo-template Правило adr-byo-template задаёт контракт для собственных шаблонов ADR: как резолвится конфиг проекта и что должен объявить шаблон, чтобы ADR Creator его принял. CX Codex +1 ★ 1 627звёзд репо pptx Задаёт структуру каталогов, форматы YAML и правила верстки для сборки презентаций PowerPoint с помощью агентов и python-pptx. CX Codex +1 ★ 1 627звёзд репо coaching-patterns Правило coaching-patterns задаёт исследовательский стиль вопросов для планирующих агентов. Оно помогает сначала разобраться в системе и её контексте, а затем переходить к классификации и анализу. CX Codex +1 ★ 1 627звёзд репо BRD Quality Reviewer Субагент BRD Quality Reviewer автоматически проверяет требования в BRD по стандартам ISO/IEC/IEEE 29148 и ISO/IEC 25010 и формирует отчёт с рекомендациями без изменения файлов. CX Codex +1 ★ 1 627звёзд репо agentic-workflows Субагент направляет задачи по GitHub Agentic Workflows к нужным сценариям: создание, обновление, отладка и обновление версий. CX Codex +1 ★ 1 627звёзд репо dt-figma-export Скилл dt-figma-export экспортирует артефакты Design Thinking методов 1, 3, 4, 5 и 6 на доски FigJam или в файлы Figma Design через MCP-сервер Figma для совместного просмотра командой. CX Codex +1 ★ 1 627звёзд репо PRD Quality Reviewer Субагент PRD Quality Reviewer проверяет черновики PRD на соответствие стандартам ISO/IEC/IEEE 29148 и NIST SP 800-160, формируя структурированные отчёты без изменения файлов. CX Codex +1 ★ 1 627звёзд репо Vally Test Author Субагент Vally Test Author создаёт блоки стимулов для тестов соответствия Vally из файлов с инструкциями или таблицы CSV/XLSX. Записывает их в подходящий eval-файл. CX Codex +1 ★ 1 627звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой