conventions
OTel observability conventions: span naming, attribute keys, PII rules, and sampling configuration
- License 许可
- MIT
- 最近更新
- 2026-03-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- conventions
- description
- OTel observability conventions: span naming, attribute keys, PII rules, and sampling configuration
02 资源文件 3
- 参考文档references/attributes.md1.8 KB
- 参考文档references/sampling.md1.3 KB
- 参考文档references/span-names.md1.5 KB
03 SKILL.md 正文
Observability Conventions
Standard conventions for OpenTelemetry instrumentation across the Lucid platform.
The 6 Rules
- Identity keys (tenant_key, session_key, user_key) MUST be hashed via
hashForTelemetry()— they are PII - UUIDs (run_id, conversation_id, message_id) are OK raw — they are NOT PII
- UUIDs are HIGH CARDINALITY — NEVER use as metric labels
- Content (plaintext, ciphertext, prompts, tool args) is NEVER an attribute
- Use
LUCID_ENVnotNODE_ENVfor environment detection - All services use head + tail sampling: head captures baseline, tail captures 100% errors
Span Names
See references/span-names.md for the canonical list of 20 span names and their descriptions.
When reviewing or writing instrumentation code:
- Use exact span names from the reference list
- Each span name maps to a specific operation
- New span names should follow the
domain.operationpattern
Attribute Keys
See references/attributes.md for all 19 standard attribute keys with PII and cardinality flags.
When reviewing attributes:
- Check PII flag — PII attributes MUST be hashed
- Check high cardinality flag — high cardinality attributes MUST NOT be metric labels
- Use the exact key names from the reference list
Sampling
See references/sampling.md for head/tail sampling configuration.
Convention Compliance Check
When auditing a service for convention compliance:
- Verify service is in the topology — check correlation/references/services.md
- Check Sentry project exists — verify the sentryProject mapping
- Check span names — service should implement spans that match its domain prefix
- Check PII handling — all PII attributes must use
hashForTelemetry() - Check sampling config — verify rates match the environment
- Check LUCID_ENV — must be set, not relying on NODE_ENV
04 同仓库更多 Skills
lucid-PLUGIN_NAME
PLUGIN_DESCRIPTION
social-content
Generate short-form video content optimized for social media platforms
personalized-outreach
Generate 1:1 personalized video for sales prospecting and customer success
data-reports
Generate animated data report videos from KPIs, charts, and analytics
lucid-video
Agent-native video generation using Remotion — MCP server + OpenClaw plugin
lucid-veille
Content monitoring, AI digest generation, and multi-platform auto-publishing