@moon791017/neo-skills 1.1.12 → 1.1.13

package/README.md

@@ -60,6 +60,7 @@
 | Vue | `neo-vue` | 建置、除錯、重構或審查 Vue 3、SFC、Composition API、Pinia、Vue Router、Vite 與 Vue+TypeScript。 |
 | Agent 架構 | `neo-sub-agent` | 設計、建立、審查或轉換 sub-agent、custom agent、worker/reviewer/planner agent 或 multi-agent workflow。 |
 | Agent 架構 | `neo-agentic-design` | 設計、評估或實作 Agent 工作流、提示詞鏈、路由、規劃、反思、多 Agent 協作與記憶體管理等框架無關模式。 |
+| 可觀測性 | `neo-opentelemetry` | 解釋 OpenTelemetry 概念、規劃或審查 Collector 架構與設定、處理維運排障、安全、零程式 instrumentation 及相容性遷移。 |
 | 文字潤飾 | `neo-stop-slop` | 去除繁中或英文中的 AI 腔、贅詞、公式化句式，支援文件、註解、commit message 與 PR 說明。 |
 
 ## 安裝
@@ -155,6 +156,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | 改善 AI 開發流程 | `neo-agent-harness` | `評估這個專案讓 coding agent 協作的可靠度` |
 | 建立 sub-agent | `neo-sub-agent` | `幫我新增一個 Codex code-reviewer sub agent` |
 | 設計 Agent 編排架構 | `neo-agentic-design` | `幫我設計一個多 Agent 客服系統的拓撲結構與重試機制` |
+| 規劃 OpenTelemetry | `neo-opentelemetry` | `幫我審查 Collector 架構、韌性、安全與零程式觀測方案` |
 | 去掉 AI 腔 | `neo-stop-slop` | `把這段 PR 說明改得自然、直接一點` |
 
 ## 開發

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "type": "module",
   "description": "Neo Skills: A Universal AI Agent Skills Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-opentelemetry/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: neo-opentelemetry
+description: >
+  Use this skill when explaining OpenTelemetry concepts, choosing telemetry signals,
+  planning or reviewing Collector architectures and declarative configuration,
+  operating or troubleshooting telemetry pipelines, securing telemetry data,
+  evaluating zero-code instrumentation, or planning Prometheus, OpenCensus, or
+  OpenTracing interoperability and migration. Do not use it to write language SDK/API
+  instrumentation code or custom Collector components.
+compatibility: No runtime required. Network access is required to verify current versions, component status, security advisories, and other time-sensitive claims.
+metadata:
+  version: "1.0.0"
+  pattern: "tool-wrapper,pipeline"
+  domain: "observability-operations"
+  source-revision: "b18eb4d01fab9be2c5c22b1aaafdeb23ba97e3d4"
+---
+
+# Neo OpenTelemetry
+
+Provide source-grounded OpenTelemetry guidance for concepts and operations without generating programming-language instrumentation code.
+
+## Scope boundary
+
+In scope:
+
+- Observability concepts, telemetry signals, correlation, resources, semantic conventions, and sampling.
+- Collector pipelines, components, deployment patterns, declarative configuration, scaling, resiliency, internal telemetry, transformation, and troubleshooting.
+- Kubernetes, FaaS, OpenTelemetry Operator, OBI, and other zero-code operational approaches.
+- Security, sensitive-data handling, Prometheus interoperability, and OpenCensus/OpenTracing migration planning.
+
+Out of scope:
+
+- Language-specific SDK/API usage, manual instrumentation, source-code examples, and library integration code.
+- Building the Collector from source or developing custom receivers, processors, exporters, connectors, or extensions.
+- Vendor pricing, backend-specific query languages, and backend product administration unless needed only as context for an OpenTelemetry decision.
+
+If the request crosses the boundary, answer the in-scope operational portion and identify the excluded portion. Point to the appropriate official language or component-development documentation instead of inventing code.
+
+## Workflow
+
+1. Classify the request as explanation, architecture decision, configuration review, security review, migration, or troubleshooting.
+2. Load `references/sources-and-scope.md` whenever the answer depends on source coverage, current status, or an excluded area.
+3. Load only the references required by the request:
+   - Foundations and terminology: `references/foundations.md`
+   - Signals and sampling: `references/signals-and-sampling.md`
+   - Collector topology and configuration: `references/collector-architecture-and-configuration.md`
+   - Collector operations and troubleshooting: `references/collector-operations.md`
+   - Kubernetes, FaaS, Operator, and zero-code: `references/platforms-and-zero-code.md`
+   - Security and sensitive data: `references/security.md`
+   - Prometheus, migration, and deployment guidance: `references/compatibility-and-guidance.md`
+4. Inspect user-provided configuration and environment evidence before recommending changes. Never assume topology, volume, failure tolerance, trust boundaries, or backend capabilities.
+5. Verify time-sensitive facts against official OpenTelemetry sources. If verification is unavailable, identify the snapshot revision and state that current status cannot be confirmed.
+6. Produce the smallest useful response and cite the official page supporting material claims.
+
+## Decision rules
+
+- Treat OpenTelemetry as a telemetry generation, collection, processing, and export framework, not as a storage or visualization backend.
+- Default to the simplest deployment pattern that satisfies the stated requirements. Add gateways, stateful routing, persistent queues, or external message queues only for an identified need.
+- Separate symptoms by pipeline stage: generation, reception, processing, queuing, export, network, or backend.
+- Treat sampling, filtering, redaction, and transformation as data-loss or data-quality decisions. State what is intentionally discarded or changed.
+- Never recommend scaling Collectors before checking whether the bottleneck is the Collector, network, or backend.
+- Never place credentials, tokens, personal data, or other sensitive values in examples.
+- Prefer least privilege, restricted listener addresses, authenticated and encrypted network paths, data minimization, and Collector self-observability.
+
+## Response contracts
+
+For explanations, provide:
+
+1. Direct answer.
+2. Relevant OpenTelemetry concepts and boundaries.
+3. Official source links.
+
+For architecture or configuration reviews, provide:
+
+1. Observed requirements or configuration facts.
+2. Findings ordered by impact.
+3. Recommended topology or declarative changes with trade-offs.
+4. Capacity, resiliency, security, and validation checks.
+5. Official source links.
+
+For troubleshooting, provide:
+
+1. Observed symptom and missing evidence.
+2. Most likely pipeline stage based on supplied evidence; label this as an inference.
+3. Non-destructive checks ordered from source to destination.
+4. Remediation only after the failing stage is isolated.
+5. Verification signals and official source links.
+
+## Fact-check gate
+
+- Distinguish verified source facts from recommendations and inferences.
+- Do not convert documentation examples into universal defaults.
+- Do not state version numbers, maturity levels, component availability, default ports, default limits, or CVE status without checking the current official source when the answer depends on them.
+- Say that data is insufficient when the request lacks evidence needed for a safe operational conclusion.

package/skills/neo-opentelemetry/evals/eval_queries.json

@@ -0,0 +1,82 @@
+[
+  {
+    "query": "Explain when I should use traces, metrics, logs, and profiles together in OpenTelemetry.",
+    "should_trigger": true
+  },
+  {
+    "query": "Review our OpenTelemetry Collector YAML for missing queues, unsafe listeners, and processor ordering.",
+    "should_trigger": true
+  },
+  {
+    "query": "Should our Kubernetes telemetry pipeline use Collector agents, gateways, or both?",
+    "should_trigger": true
+  },
+  {
+    "query": "Our otel gateway queue keeps filling and spans are being dropped. Help me isolate the bottleneck.",
+    "should_trigger": true
+  },
+  {
+    "query": "Design a resilient OpenTelemetry Collector topology that can tolerate a backend outage.",
+    "should_trigger": true
+  },
+  {
+    "query": "Check whether our baggage and resource attributes could leak customer data.",
+    "should_trigger": true
+  },
+  {
+    "query": "Plan a zero-code observability rollout for Linux workloads using the Operator or OBI.",
+    "should_trigger": true
+  },
+  {
+    "query": "How should we migrate Prometheus metric collection into an OTLP and Collector architecture?",
+    "should_trigger": true
+  },
+  {
+    "query": "Create an operational migration plan from OpenTracing to OpenTelemetry without breaking dashboards.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why are traces split after they cross a service boundary even though both services export spans?",
+    "should_trigger": true
+  },
+  {
+    "query": "Write C# ActivitySource instrumentation for my ASP.NET Core checkout endpoint.",
+    "should_trigger": false
+  },
+  {
+    "query": "Show me the Java OpenTelemetry SDK calls needed to create a custom histogram.",
+    "should_trigger": false
+  },
+  {
+    "query": "Implement a custom OpenTelemetry Collector receiver in Go.",
+    "should_trigger": false
+  },
+  {
+    "query": "Build the OpenTelemetry Collector from source with a custom exporter.",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a PromQL query for calculating HTTP error rate in Grafana.",
+    "should_trigger": false
+  },
+  {
+    "query": "Troubleshoot why my Kubernetes Deployment cannot pull its application image.",
+    "should_trigger": false
+  },
+  {
+    "query": "Compare the current pricing of Datadog, New Relic, and Honeycomb.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create OpenAPI documentation for my REST endpoints.",
+    "should_trigger": false
+  },
+  {
+    "query": "Help me submit a pull request to translate the OpenTelemetry website.",
+    "should_trigger": false
+  },
+  {
+    "query": "Design a generic application logging API that does not use OpenTelemetry.",
+    "should_trigger": false
+  }
+]

package/skills/neo-opentelemetry/evals/evals.json

@@ -0,0 +1,64 @@
+{
+  "skill_name": "neo-opentelemetry",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We operate a checkout service and only have CPU dashboards. Explain which OpenTelemetry signals would help us detect reliability problems and determine why one request is slow. Do not provide instrumentation code.",
+      "expected_output": "A source-grounded explanation that distinguishes metrics, traces, logs, and profiles, describes correlation, and stays outside language SDK/API implementation.",
+      "assertions": [
+        "The response explains a distinct operational question answered by metrics, traces, logs, and profiles",
+        "The response explains that resource identity or trace context is needed for correlation",
+        "The response contains at least one official opentelemetry.io documentation link",
+        "The response contains no programming-language instrumentation code"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Plan an OpenTelemetry Collector deployment for 60 Kubernetes nodes. We need node logs and host metrics, centralized redaction, one controlled egress point, and tail sampling for traces. State assumptions where capacity data is missing.",
+      "expected_output": "An agent-to-gateway architecture with node-local agents, centralized gateway processing, trace-affine routing for tail sampling, explicit security and capacity caveats, and verification steps.",
+      "assertions": [
+        "The response assigns node logs and host metrics to node-local agents",
+        "The response assigns centralized redaction, credentials, and backend export to gateways",
+        "The response states that every span for a trace must reach the same tail-sampling instance",
+        "The response labels capacity recommendations as unresolved because telemetry volume is not provided",
+        "The response includes security, resiliency, and rollout verification checks"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review this Collector configuration:\n\nreceivers:\n  otlp:\n    protocols:\n      grpc:\n        endpoint: 0.0.0.0:4317\nprocessors:\n  batch:\nexporters:\n  otlp:\n    endpoint: vendor.example:4317\n    headers:\n      api-key: hard-coded-example-secret\nservice:\n  pipelines:\n    traces:\n      receivers: [otlp]\n      processors: [batch]\n      exporters: [otlp]\n\nIdentify operational and security risks, but do not assume whether remote clients require the unrestricted listener.",
+      "expected_output": "A configuration review that identifies the unrestricted listener, embedded secret, missing memory protection, queue/retry and TLS questions, while treating topology-dependent changes as conditional.",
+      "assertions": [
+        "The response identifies the embedded credential as a critical issue and recommends protected runtime secret injection",
+        "The response identifies 0.0.0.0 as an exposure requiring topology evidence rather than replacing it unconditionally",
+        "The response checks memory limiting, batching, queueing, retries, TLS, and Collector self-observability",
+        "Findings are ordered by impact and distinguish facts from conditional recommendations",
+        "The response includes official Collector configuration and security links"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "During a backend outage our Collector exporter queue reaches capacity, enqueue failures increase, and queued data disappears when gateway pods restart. Give us a diagnosis and a resilient remediation sequence.",
+      "expected_output": "A diagnosis grounded in queue saturation and in-memory loss, followed by bounded retry/queue tuning, persistent storage evaluation, monitoring, capacity checks, and an optional external queue only when stronger durability justifies it.",
+      "assertions": [
+        "The response identifies queue saturation and pod restart with in-memory buffering as observed loss mechanisms",
+        "The response recommends measuring arrival rate, outage duration, queue capacity, memory, disk, and backend recovery before sizing",
+        "The response discusses persistent sending queues and their disk and permission trade-offs",
+        "The response treats an external message queue as an optional higher-complexity durability layer",
+        "The response defines post-change verification using queue, failure, restart, and export evidence"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "We want zero-code telemetry for mixed workloads: Kubernetes services, Linux VMs, and AWS Lambda. Produce a decision framework that covers the Operator, OBI, Collector agents, and Lambda layers. Current versions and runtime details are not supplied.",
+      "expected_output": "A platform-specific decision framework that compares supported zero-code approaches, flags missing compatibility evidence, includes least-privilege and rollout checks, and avoids unsupported version claims or language code.",
+      "assertions": [
+        "The response maps the Operator to Kubernetes, OBI or Collector agents to compatible Linux environments, and published layers to supported Lambda runtimes",
+        "The response states that runtime, kernel, architecture, region, artifact, and current-version compatibility must be verified",
+        "The response includes least-privilege, network, secret, performance, and rollback checks",
+        "The response identifies that zero-code methods cannot guarantee custom business telemetry",
+        "The response contains no manual instrumentation code"
+      ]
+    }
+  ]
+}

package/skills/neo-opentelemetry/references/collector-architecture-and-configuration.md

@@ -0,0 +1,138 @@
+# Collector Architecture and Configuration
+
+Use this reference to choose a Collector topology or review declarative Collector configuration. Component availability and configuration keys vary by distribution and version; verify them in the current component documentation.
+
+## Pipeline model
+
+A Collector pipeline moves one signal type through:
+
+1. Receivers that accept or obtain telemetry.
+2. Optional processors that transform, enrich, batch, sample, filter, or drop telemetry.
+3. Exporters that send telemetry to a destination.
+
+Connectors join two pipelines while acting as an exporter for one and a receiver for another. Extensions add operational capabilities such as health checks, storage, authentication, or service discovery and are enabled separately from telemetry pipelines.
+
+A minimal declarative shape is:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 512
+  batch:
+
+exporters:
+  otlp:
+    endpoint: telemetry-backend.example:4317
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlp]
+```
+
+This is a structural example, not a production-ready universal default. Authentication, TLS, listener addresses, queueing, resource limits, and component support must be decided for the target environment.
+
+## Configuration mechanics
+
+- Define components at the top level, then activate them by referencing them from a pipeline or the service extension list.
+- Use `type/name` identifiers when more than one instance of a component type is needed.
+- A defined component that is not referenced by `service` is not enabled.
+- Signal types in a pipeline must be supported by every referenced component.
+- Processor order is behaviorally significant.
+- Multiple configuration sources can be merged, but the merged result must still be complete.
+- Use environment-variable substitution for deployment-supplied values; never embed secrets in the Skill, repository examples, or review output.
+
+Validate before deployment:
+
+```shell
+otelcol validate --config=collector.yaml
+```
+
+Confirm the executable and subcommand for the selected Collector distribution rather than assuming every distribution uses the same binary name.
+
+## Reuse and fan-out gotcha
+
+A receiver can feed multiple pipelines and an exporter can receive from multiple pipelines. Receiver fan-out is synchronous: a blocking processor in one attached pipeline can block the other pipelines and the receiver. Do not reuse a receiver across pipelines without evaluating this failure coupling.
+
+Processors referenced by multiple pipelines use the same configuration but each pipeline gets its own processor instance and state.
+
+## Deployment patterns
+
+### No Collector
+
+Direct export has the fewest moving parts but couples telemetry delivery and backend changes to the instrumented workload. Use it for simple development or constrained cases only after accepting the limited processing, exporter, and operational flexibility.
+
+### Agent
+
+An agent runs close to workloads, commonly as a host process, sidecar, or Kubernetes DaemonSet.
+
+Choose an agent when you need:
+
+- Host-local metrics or logs.
+- Local enrichment with host or Kubernetes resource attributes.
+- A stable local telemetry destination.
+- Reduced application responsibility for credentials and backend export.
+
+Agents multiply configuration and resource overhead across hosts or workloads. Keep their processing focused.
+
+### Gateway
+
+A gateway is a standalone Collector service shared by multiple telemetry sources.
+
+Choose a gateway when you need:
+
+- Centralized credentials, filtering, transformation, or policy.
+- Central processing that must observe traffic from multiple sources.
+- Independent scaling of telemetry processing.
+- A controlled egress point to external backends.
+
+Gateways add a network hop and a shared failure domain. Load balance stateless gateways and monitor them as production services.
+
+### Agent to gateway
+
+Combine agents and gateways when both local collection and centralized processing are required. Typical separation:
+
+- Agents: local reception, host collection, resource detection, memory protection, and efficient forwarding.
+- Gateways: centralized filtering, tail sampling, batching, credentials, and resilient export.
+
+This pattern is justified by identified needs such as network isolation, host telemetry, central policy, trace-aware sampling, or scale. It is not the default for small deployments.
+
+## Stateful routing rules
+
+- Tail sampling requires all spans for a trace to reach the same decision-making instance.
+- Cumulative-to-delta conversion and some aggregation use cases also require data-aware routing.
+- Prometheus scraping requires target allocation or sharding to avoid duplicate collection.
+- Metric streams must preserve the single-writer principle and globally unique identities.
+- Standard layer-4 load balancing can be ineffective for persistent gRPC connections; verify that the load-balancing method distributes the actual connection pattern.
+
+## Configuration review checklist
+
+1. Identify each enabled pipeline and its signal type.
+2. Verify every referenced component exists in the selected distribution.
+3. Trace data from each receiver through processors to every exporter.
+4. Inspect processor order and intentional data drops.
+5. Check listener scope, authentication, TLS, and secret injection.
+6. Check memory limiting, batching, queueing, retry, and persistent storage requirements.
+7. Check stateful processors and their routing assumptions.
+8. Check resource identity and duplicate-writer risk.
+9. Check Collector internal telemetry, health checks, and alerting.
+10. Validate the merged configuration with the target executable.
+
+## Official sources
+
+- [Collector architecture](https://opentelemetry.io/docs/collector/architecture/)
+- [Collector configuration](https://opentelemetry.io/docs/collector/configuration/)
+- [Collector components](https://opentelemetry.io/docs/collector/components/)
+- [Choose a deployment pattern](https://opentelemetry.io/docs/collector/deploy/choose/)
+- [Agent deployment pattern](https://opentelemetry.io/docs/collector/deploy/agent/)
+- [Gateway deployment pattern](https://opentelemetry.io/docs/collector/deploy/gateway/)
+- [Agent-to-gateway deployment pattern](https://opentelemetry.io/docs/collector/deploy/other/agent-to-gateway/)
+- [No Collector](https://opentelemetry.io/docs/collector/deploy/other/no-collector/)

package/skills/neo-opentelemetry/references/collector-operations.md

@@ -0,0 +1,137 @@
+# Collector Operations and Troubleshooting
+
+Use this reference for installation planning, self-observability, capacity, resiliency, transformation, and incident diagnosis.
+
+## Installation and distribution checks
+
+Before using any component or command, confirm:
+
+- Target operating system or Kubernetes environment.
+- Collector distribution and version.
+- Included receivers, processors, exporters, connectors, and extensions.
+- Configuration file location and executable name.
+- Required network access, filesystem access, capabilities, and credentials.
+
+Do not assume the core and contrib distributions contain the same components. Registry listings and component maturity are time-sensitive and require current verification.
+
+## Internal telemetry
+
+The Collector must expose enough telemetry to distinguish its own saturation from upstream, network, or backend failures. Monitor at least:
+
+- Accepted and refused telemetry by receiver and signal.
+- Processor drops and refusals.
+- Export successes, permanent failures, and enqueue failures.
+- Exporter queue size and capacity.
+- CPU, memory, and restart behavior.
+- Request latency and errors for downstream destinations.
+- Scrape duration relative to scrape interval for pull-based receivers.
+
+Metric names can change across versions. Confirm the current names before creating alerts; use the names documented by the installed version.
+
+## Scaling decision flow
+
+1. Split demand by signal, protocol, and collection behavior.
+2. Identify whether components are stateless, scrapers, or stateful.
+3. Check refusal, queue, resource, and downstream latency evidence.
+4. Determine whether the constraint is Collector CPU/memory, a scrape schedule, the network, or the backend.
+5. Scale only the constrained tier and preserve stateful routing rules.
+
+Scaling patterns:
+
+- Stateless receivers and processors can usually scale horizontally behind a suitable load balancer.
+- Scrapers require target sharding or allocation to prevent duplicate collection.
+- Stateful processors require affinity and careful redistribution behavior.
+- Signal-specific Collector tiers can isolate failures and scale independently.
+
+Do not add Collectors when the exporter queue remains full because the backend or network cannot accept more traffic. That can increase pressure without increasing throughput.
+
+## Resiliency layers
+
+### In-memory sending queue
+
+Buffers transient downstream failures and works with retries. Data can still be lost when the queue fills, retry limits expire, or the Collector terminates.
+
+### Persistent sending queue
+
+A storage extension can back the sending queue with a write-ahead log so queued data survives Collector restarts. It introduces disk capacity, permissions, corruption, and lifecycle requirements.
+
+```yaml
+extensions:
+  file_storage:
+    directory: /var/lib/otelcol/storage
+
+exporters:
+  otlp:
+    endpoint: telemetry-backend.example:4317
+    sending_queue:
+      storage: file_storage
+
+service:
+  extensions: [file_storage]
+```
+
+Treat the directory, retention, queue size, and retry duration as workload-specific settings.
+
+### External message queue
+
+An external queue can decouple Collector tiers and provide stronger durability across outages. It also creates another production system with its own availability, retention, security, ordering, and capacity requirements. Add it only when the required durability and failure isolation justify the operational cost.
+
+## Data-loss checklist
+
+Check for:
+
+- Downstream unavailability exceeding retry duration.
+- Full sending queues or persistent storage.
+- Collector restart with only in-memory buffering.
+- Disk failure or exhausted persistent storage.
+- External queue outage or retention expiration.
+- Receiver, processor, exporter, or routing misconfiguration.
+- Sampling or filtering that intentionally discards data.
+- Load-balancing that splits state required by a processor.
+- Backend rejection, throttling, or duplicate metric writers.
+
+## Transformation safety
+
+Transformations can normalize, enrich, redact, filter, or route telemetry. Before applying one:
+
+1. Define the exact operational purpose.
+2. Identify affected signals and attributes.
+3. Preserve resource identity and semantic meaning.
+4. Quantify records that will be dropped or rewritten.
+5. Test representative and malformed input.
+6. Monitor transform errors and output volume after rollout.
+
+Prefer allowlists for sensitive attributes and explicit filters for unwanted data. Avoid transformations that silently collapse distinct metric streams or break trace correlation.
+
+## Troubleshooting sequence
+
+Diagnose from source to destination:
+
+1. Confirm the source is producing the expected signal.
+2. Confirm network reachability and protocol compatibility to the receiver.
+3. Confirm the receiver accepts records and attaches expected resource data.
+4. Inspect processor refusals, errors, sampling, filtering, and transformations.
+5. Inspect queue occupancy, retries, enqueue failures, and storage health.
+6. Inspect exporter errors, TLS, authentication, endpoint, and timeouts.
+7. Confirm the backend accepts, indexes, and exposes the data.
+
+Useful non-destructive actions include validating the active configuration, raising Collector log detail temporarily, using diagnostic extensions or a debug exporter in a controlled environment, and comparing accepted versus exported counts. Do not enable verbose telemetry in production without considering sensitive data and volume.
+
+## Change verification
+
+- Validate configuration before restart.
+- Roll out to a limited Collector subset when possible.
+- Compare accepted, dropped, queued, retried, and exported telemetry before and after.
+- Confirm resource identity, trace completeness, metric continuity, and log timestamps.
+- Confirm rollback conditions and configuration are ready.
+
+## Official sources
+
+- [Collector installation](https://opentelemetry.io/docs/collector/install/)
+- [Collector internal telemetry](https://opentelemetry.io/docs/collector/internal-telemetry/)
+- [Collector management](https://opentelemetry.io/docs/collector/management/)
+- [Scaling the Collector](https://opentelemetry.io/docs/collector/scaling/)
+- [Collector resiliency](https://opentelemetry.io/docs/collector/resiliency/)
+- [Transforming telemetry](https://opentelemetry.io/docs/collector/transforming-telemetry/)
+- [Collector troubleshooting](https://opentelemetry.io/docs/collector/troubleshooting/)
+- [Collector registry](https://opentelemetry.io/docs/collector/registry/)

package/skills/neo-opentelemetry/references/compatibility-and-guidance.md

@@ -0,0 +1,112 @@
+# Compatibility, Migration, and Platform Guidance
+
+Use this reference for Prometheus interoperability, OpenCensus/OpenTracing migration planning, and organization-level telemetry-platform decisions. Programming-language migration code remains outside this skill.
+
+## Prometheus interoperability
+
+Prometheus is built around discovering and scraping targets. OpenTelemetry also supports transporting metrics through OTLP. Newer Prometheus versions can receive OTLP metrics, but the official OpenTelemetry guidance recommends a Collector intermediary for production OpenTelemetry deployments.
+
+Key differences to preserve during migration or translation:
+
+- Prometheus traditionally uses pull-based scraping; OTLP commonly pushes telemetry.
+- Metric naming, units, suffixes, and resource-to-label mapping can change during translation.
+- Prometheus metrics are cumulative; OpenTelemetry supports more than one aggregation temporality, while Prometheus-facing export requires compatible cumulative behavior.
+- OpenTelemetry resource identity maps into Prometheus target identity and related metadata.
+- Instrumentation-scope labels can distinguish otherwise identical metric names.
+- Duplicate writers or duplicate scrapes can create invalid or out-of-order series.
+
+Operational patterns:
+
+- Use Prometheus receivers when the Collector must scrape existing targets.
+- Use the Target Allocator or another sharding mechanism when multiple Collectors scrape Kubernetes targets.
+- Use a Collector between OTLP producers and Prometheus for central policy, conversion, buffering, and diagnostics.
+- Verify the current Prometheus OTLP receiver requirements before recommending direct ingestion.
+
+## Migration principles
+
+Treat migration as a telemetry-contract change, not only a deployment change.
+
+1. Inventory existing signals, protocols, resource identity, propagation, baggage, dashboards, alerts, SLOs, and retention rules.
+2. Define the target OTLP and Collector topology.
+3. Establish a compatibility or overlap period when supported.
+4. Migrate one bounded telemetry path at a time.
+5. Compare old and new volume, identity, attributes, trace continuity, metric continuity, dashboards, and alerts.
+6. Update downstream consumers before removing the old feed.
+7. Remove compatibility layers only after acceptance criteria pass.
+
+### OpenTracing
+
+OpenTelemetry documents an incremental migration path using compatibility shims, but shim and language details are outside this skill and must be checked in current language documentation.
+
+Operational risks that remain in scope:
+
+- Semantic-convention changes can break dashboards and alerts.
+- Baggage behavior differs and can lose propagation when old and new mechanisms are mixed.
+- Context-management differences can fragment traces.
+- Dual export can duplicate telemetry and increase cost.
+- A Collector transformation can provide a temporary compatibility view, but it must have a removal plan.
+
+### OpenCensus
+
+The local documentation entry redirects to the current OpenTelemetry migration guidance rather than containing an operational procedure. Verify the current official migration page and target-language support before planning implementation. Do not invent a generic shim or compatibility guarantee.
+
+## Organization-level platform guidance
+
+### Non-Kubernetes environments
+
+Common challenges include fragmented agent deployment, inconsistent instrumentation, and siloed export paths. A managed approach can:
+
+- Define baseline telemetry and resource-attribution standards.
+- Centrally manage agent lifecycle with controlled workload overrides.
+- Use a Collector gateway layer for shared policy and backend export.
+- Separate global defaults, environment policy, and workload-specific configuration.
+- Monitor configuration rollout and agent/Collector health.
+
+### Kubernetes environments
+
+A managed telemetry platform can:
+
+- Distribute consistent defaults through the Operator, Helm, or internal platform automation.
+- Give application teams controlled override points without duplicating complete configurations.
+- Maintain shared gateway tiers for policy, credentials, and backend routing.
+- Process and sample at the layer that has the required data scope.
+- Establish joint ownership among platform, observability, security, and workload teams.
+
+Avoid one unbounded shared configuration for every signal and team. Separate pipelines or tiers where load, failure domains, state, or ownership differ.
+
+## Reference implementation lessons
+
+Official reference implementations describe real organizations, not universal blueprints. Extract constraints and trade-offs rather than copying their topology.
+
+Recurring lessons include:
+
+- Start with a simple path and add tiers only when requirements justify them.
+- Centralize lifecycle management and safe defaults.
+- Keep workload-facing configuration minimal and extensible.
+- Separate high-volume or stateful processing from simple collection.
+- Plan for component deprecation and controlled upgrades.
+- Monitor the telemetry platform itself.
+
+When citing a reference implementation, label the design as that organization's experience rather than an OpenTelemetry requirement.
+
+## Migration acceptance criteria
+
+- Required signals arrive with stable service and resource identity.
+- Trace context remains continuous across migrated boundaries.
+- Metric names, units, temporality, and labels meet the target contract.
+- Dashboards, alerts, and SLOs have equivalent or intentionally changed behavior.
+- Expected telemetry volume, cardinality, and cost remain within limits.
+- Sensitive-data and access controls remain effective.
+- Rollback and overlap behavior are tested.
+- Old exporters, shims, routes, and dashboards have an explicit retirement point.
+
+## Official sources
+
+- [OpenTelemetry compatibility](https://opentelemetry.io/docs/compatibility/)
+- [Prometheus interoperability](https://opentelemetry.io/docs/compatibility/prometheus/)
+- [OTLP metrics export to Prometheus](https://opentelemetry.io/docs/compatibility/prometheus/otlp-metrics-export/)
+- [Migrating from OpenCensus](https://opentelemetry.io/docs/compatibility/migration/opencensus/)
+- [Migrating from OpenTracing](https://opentelemetry.io/docs/compatibility/migration/opentracing/)
+- [Infrastructure and processes in non-Kubernetes environments](https://opentelemetry.io/docs/guidance/blueprints/instrumenting-applications-and-processes-on-nonk8s-environments/)
+- [Managed telemetry platforms for Kubernetes workloads](https://opentelemetry.io/docs/guidance/blueprints/managed-telemetry-platforms-for-k8s-workloads/)
+- [Reference implementations](https://opentelemetry.io/docs/guidance/reference-implementations/)

package/skills/neo-opentelemetry/references/foundations.md

@@ -0,0 +1,98 @@
+# OpenTelemetry Foundations
+
+Use this reference for definitions, system boundaries, correlation, resources, semantic conventions, and terminology. Do not use it for language-specific instrumentation.
+
+## What OpenTelemetry is
+
+OpenTelemetry is an open-source, vendor- and tool-agnostic framework and toolkit for generating, collecting, processing, and exporting telemetry such as traces, metrics, and logs. It is not an observability backend: storage, querying, and visualization are provided by other systems.
+
+This distinction prevents two common category errors:
+
+- Choosing OpenTelemetry does not choose the telemetry storage or user interface.
+- Changing a backend does not necessarily require changing how telemetry is represented or transported when both sides support OpenTelemetry standards.
+
+OpenTelemetry's operational building blocks include the OpenTelemetry Protocol (OTLP), semantic conventions, automatic instrumentation, the Collector, the Kubernetes Operator, Helm charts, and FaaS assets. Programming-language APIs, SDKs, and manual instrumentation are intentionally outside this skill.
+
+## Observability and reliability
+
+Observability is the ability to reason about a system's internal state from its outputs, including novel failure modes that were not predicted in advance. Telemetry is the emitted data used for that reasoning.
+
+Reliability asks whether a service delivers the behavior its users expect. Availability alone is not sufficient. A Service Level Indicator (SLI) measures behavior, ideally from the user's perspective; a Service Level Objective (SLO) connects one or more SLIs to an organizational reliability target.
+
+Use signals together:
+
+- Metrics reveal aggregate behavior and trends.
+- Traces explain the path and timing of individual requests.
+- Logs record discrete events and become more useful when correlated with traces.
+- Profiles identify where resources are consumed and can be correlated with other signals.
+
+## Context and propagation
+
+Context contains information used to correlate work across service or execution boundaries. Propagation moves that context between processes or services by serializing it into a carrier and recovering it downstream. The default OpenTelemetry propagator uses W3C Trace Context headers.
+
+Operational consequences:
+
+- Broken propagation produces disconnected traces even when every service emits spans.
+- Trace and span identifiers can correlate logs with the request that produced them.
+- Incoming context from untrusted sources can be forged; outgoing context can disclose internal information.
+- Baggage travels across boundaries and must not contain credentials, tokens, personal data, or other sensitive values.
+
+Manual propagation implementation is outside this skill. Diagnose propagation by verifying carrier presence, trust-boundary policy, and continuity of trace and parent identifiers.
+
+## Resources
+
+A resource describes the entity producing telemetry. Typical dimensions include service identity, host, operating system, process, container, Kubernetes workload, and cloud platform.
+
+Resource guidance:
+
+- Make service identity explicit and stable enough to distinguish logical services.
+- Use semantic-convention attribute names where defined.
+- Use resource detection for environmental facts, then verify the detected values.
+- Avoid attributes whose values change per request; those belong on individual telemetry records, not the producing resource.
+- Ensure identities remain globally distinguishable when multiple Collectors or environments report to the same backend.
+
+## Instrumentation scope
+
+Instrumentation scope identifies the logical source that emitted telemetry. Its identity includes a required name and optional version, schema URL, and attributes. Backends can use the scope to filter, group, or compare telemetry from different components or versions.
+
+Keep resource and scope separate:
+
+- Resource answers “what entity produced this telemetry?”
+- Instrumentation scope answers “what logical instrumentation source produced this record?”
+
+## Semantic conventions
+
+Semantic conventions standardize names and meanings for common operations and resources. They make telemetry portable and comparable across sources and backends.
+
+When reviewing telemetry:
+
+1. Check whether an applicable convention exists.
+2. Check the current convention version and stability before asserting a field is required or stable.
+3. Preserve the semantic meaning during transformation; renaming without a mapping can break dashboards, alerts, and queries.
+4. Treat custom attributes as additions, not replacements for applicable standard attributes.
+
+## Terminology checkpoints
+
+| Term | Operational meaning |
+| --- | --- |
+| Telemetry | Data emitted by a system about its behavior. |
+| Signal | A category of telemetry, such as traces, metrics, logs, baggage, or profiles. |
+| OTLP | The standard OpenTelemetry protocol for telemetry transport. |
+| Resource | Metadata describing the entity that produced telemetry. |
+| Attribute | Key-value metadata attached to telemetry. |
+| Context | Correlation state associated with an execution. |
+| Propagation | Movement of context across boundaries. |
+| Baggage | User-defined contextual key-value data propagated alongside context. |
+| Instrumentation scope | Identity of the logical source that emitted telemetry. |
+| Collector | A vendor-agnostic service that receives, processes, and exports telemetry. |
+
+## Official sources
+
+- [What is OpenTelemetry?](https://opentelemetry.io/docs/what-is-opentelemetry/)
+- [Observability primer](https://opentelemetry.io/docs/concepts/observability-primer/)
+- [Components](https://opentelemetry.io/docs/concepts/components/)
+- [Context propagation](https://opentelemetry.io/docs/concepts/context-propagation/)
+- [Resources](https://opentelemetry.io/docs/concepts/resources/)
+- [Instrumentation scope](https://opentelemetry.io/docs/concepts/instrumentation-scope/)
+- [Semantic conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)
+- [Glossary](https://opentelemetry.io/docs/concepts/glossary/)

package/skills/neo-opentelemetry/references/platforms-and-zero-code.md

@@ -0,0 +1,108 @@
+# Platforms and Zero-Code Instrumentation
+
+Use this reference when telemetry must be added or operated without editing application source. Do not turn it into language-specific integration guidance.
+
+## Zero-code model
+
+Zero-code instrumentation adds telemetry capabilities without application source changes. Depending on the environment, it can use runtime agents, process injection, platform hooks, bytecode techniques, monkey patching, or eBPF.
+
+It commonly captures framework-visible activity such as inbound and outbound requests, database calls, and messaging operations. It generally cannot infer custom business events, application-specific attributes, or arbitrary internal operations that are not visible to the mechanism.
+
+Operational configuration usually includes:
+
+- Service and resource identity.
+- Enabled instrumentations or observed protocols.
+- Export destination and transport.
+- Propagators and context behavior.
+- Sampling and signal enablement.
+- Resource limits and performance controls.
+
+Verify current support for the target language, runtime, framework, operating system, and deployment platform. Do not infer support from a different runtime.
+
+## Selection guide
+
+| Approach | Best fit | Main trade-offs |
+| --- | --- | --- |
+| Runtime or language agent | Supported runtimes where library-level operations must be observed without source changes | Runtime-specific support, startup and performance impact, version compatibility |
+| Kubernetes Operator injection | Centrally managed Kubernetes workloads with supported automatic-instrumentation images | Admission/injection policy, image lifecycle, resource overhead, rollout coordination |
+| OBI/eBPF | Linux environments requiring protocol and network visibility without process-level source changes | Kernel, architecture, privileges, protocol visibility, and application-detail limitations |
+| FaaS layer | Supported serverless runtimes where a published instrumentation or Collector layer is available | Cold-start impact, regional artifacts, layer lifecycle, limited runtime control |
+| Collector-only infrastructure collection | Host, container, Kubernetes, network, and existing log or metric sources | Does not create application-internal spans that the Collector cannot observe |
+
+## Kubernetes
+
+Choose the Collector mode based on the data source and processing requirement:
+
+- DaemonSet for node-local collection such as host metrics and node logs.
+- Sidecar when a workload requires strong local isolation or per-workload collection behavior.
+- Deployment or StatefulSet for shared gateways, central processing, or components with identity/state requirements.
+
+The OpenTelemetry Operator can manage Collector custom resources and inject supported automatic instrumentation. Helm charts provide another declarative deployment mechanism. Treat Operator and chart versions as time-sensitive and verify their current custom-resource fields and defaults.
+
+### Prometheus collection
+
+Avoid having multiple Collectors scrape the same target. The Target Allocator separates target discovery from collection and distributes Prometheus targets across Collector instances. Verify the reconciled configuration because enabling allocation can replace existing service-discovery entries with allocator-provided discovery.
+
+### Horizontal scaling
+
+Before enabling autoscaling:
+
+1. Set realistic CPU and memory requests and limits.
+2. Confirm the metrics source used by the autoscaler.
+3. Choose signals that reflect Collector pressure rather than only host utilization.
+4. Preserve stateful-routing requirements.
+5. Set minimum capacity for failure tolerance and maximum capacity for backend protection.
+
+## OpenTelemetry eBPF Instrumentation (OBI)
+
+OBI observes Linux application executables and networking with eBPF and can emit application, network, trace, metric, and correlation data without source changes. Its precise protocol coverage, feature status, artifacts, kernel requirements, and supported architectures change over time; verify the current OBI documentation.
+
+Selection constraints:
+
+- Linux kernel and BTF compatibility.
+- Supported CPU architecture.
+- Access to process, network, and kernel interfaces.
+- Required Linux capabilities for the enabled features.
+- Visibility limits for encrypted, asynchronous, runtime-specific, or application-specific behavior.
+- Cardinality and telemetry-volume controls.
+
+Use least privilege. Prefer the exact capabilities required by enabled features over unrestricted root access. Treat `CAP_SYS_ADMIN` and host-level access as high-risk and document why they are needed.
+
+OBI is not a substitute for custom business telemetry. If the requirement depends on application semantics that OBI cannot observe, identify that limitation without generating manual instrumentation code.
+
+## FaaS
+
+Serverless environments have platform-specific lifecycle, startup, networking, and packaging constraints. For supported Lambda layers:
+
+- Confirm the layer exists for the runtime and region.
+- Account for initialization and cold-start overhead.
+- Add a Collector layer or verified external Collector path when the instrumentation layer requires it.
+- Configure secrets through the platform secret mechanism or protected environment injection.
+- Verify the transport, endpoint, and layer compatibility before rollout.
+- Publish and test a new function version with rollback available.
+
+Do not copy version numbers or layer ARNs from a snapshot. Resolve the current official release for the target region at execution time.
+
+## Rollout checklist
+
+1. Inventory platform, runtime, kernel, architecture, and workload restrictions.
+2. Confirm the zero-code method supports the target.
+3. Define expected signals and known blind spots.
+4. Establish service/resource identity and export path.
+5. Review privileges, network exposure, and secrets.
+6. Measure startup, CPU, memory, latency, and telemetry volume on a limited rollout.
+7. Verify trace continuity, metric cardinality, log correlation, and backend ingestion.
+8. Document rollback and upgrade ownership.
+
+## Official sources
+
+- [Zero-code instrumentation concept](https://opentelemetry.io/docs/concepts/instrumentation/zero-code/)
+- [Zero-code instrumentation documentation](https://opentelemetry.io/docs/zero-code/)
+- [OpenTelemetry eBPF Instrumentation](https://opentelemetry.io/docs/zero-code/obi/)
+- [OBI security, permissions, and capabilities](https://opentelemetry.io/docs/zero-code/obi/security/)
+- [OpenTelemetry with Kubernetes](https://opentelemetry.io/docs/platforms/kubernetes/)
+- [OpenTelemetry Operator](https://opentelemetry.io/docs/platforms/kubernetes/operator/)
+- [Target Allocator](https://opentelemetry.io/docs/platforms/kubernetes/operator/target-allocator/)
+- [Functions as a Service](https://opentelemetry.io/docs/platforms/faas/)
+- [Lambda auto-instrumentation](https://opentelemetry.io/docs/platforms/faas/lambda-auto-instrument/)
+- [Lambda Collector configuration](https://opentelemetry.io/docs/platforms/faas/lambda-collector/)

package/skills/neo-opentelemetry/references/security.md

@@ -0,0 +1,119 @@
+# OpenTelemetry Security
+
+Use this reference for Collector hardening, sensitive-data controls, context trust boundaries, and security review. OpenTelemetry cannot decide which data is sensitive for a particular organization; that responsibility remains with the operator.
+
+## Security objectives
+
+- Minimize telemetry collection to data with an explicit observability purpose.
+- Protect telemetry in transit, in memory, on disk, and in the backend.
+- Restrict Collector listeners and administrative endpoints.
+- Authenticate peers and authorize access.
+- Run with the least filesystem, network, Kubernetes, and kernel privilege.
+- Prevent resource exhaustion and uncontrolled cardinality.
+- Keep credentials out of configuration files and telemetry.
+- Monitor current OpenTelemetry security advisories.
+
+## Sensitive data
+
+Potentially sensitive telemetry includes personal information, credentials, session tokens, financial or health data, user behavior, request and response content, database statements, URLs, headers, logs, and baggage.
+
+Apply controls in this order:
+
+1. Do not collect unnecessary data.
+2. Prefer aggregation, truncation, or categorization over unique identifiers.
+3. Use an allowlist when the acceptable attribute set is known.
+4. Remove or mask sensitive values before they cross a trust boundary.
+5. Restrict access and retention for telemetry that must remain identifiable.
+6. Periodically inspect actual emitted telemetry because instrumentation and schemas change.
+
+Hashing does not automatically anonymize predictable values. A small or enumerable input space can permit reversal by guessing. Document the threat model before treating hashing as a privacy control.
+
+## Collector network hardening
+
+- Bind server-like components to the narrowest required interface. Prefer loopback for local-only clients.
+- Do not expose receivers, health endpoints, diagnostics, or management endpoints to the public internet without an explicit design.
+- Use TLS for network hops that cross trust boundaries.
+- Authenticate receivers and exporters where supported.
+- Restrict inbound and outbound traffic with platform network controls.
+- Review trust separately for application-to-agent, agent-to-gateway, and gateway-to-backend hops.
+
+An illustrative local-only receiver is:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 127.0.0.1:4317
+```
+
+Container and Kubernetes networking can make loopback inappropriate for cross-container traffic. Select the interface from the actual topology rather than replacing it with unrestricted `0.0.0.0` by default.
+
+## Secrets and configuration
+
+- Store secrets in the deployment platform's protected secret mechanism.
+- Inject secret values at runtime; do not commit them in Collector YAML.
+- Restrict read access to configuration, certificates, queues, WAL directories, and raw telemetry.
+- Avoid printing resolved configuration or verbose telemetry where secrets may appear.
+- Rotate credentials and certificates without requiring broad unrelated configuration changes.
+
+Use placeholders in examples:
+
+```yaml
+exporters:
+  otlp:
+    endpoint: telemetry-backend.example:4317
+    headers:
+      authorization: ${env:OTEL_EXPORTER_AUTHORIZATION}
+```
+
+## Least privilege
+
+- Avoid running the Collector as root unless a required data source cannot be accessed otherwise.
+- Grant read-only filesystem mounts when collection does not require writes.
+- Scope Kubernetes RBAC to the resources and verbs required by enabled receivers, processors, observers, or the Operator.
+- Review observer and service-discovery extensions because discovery can require broad environment visibility.
+- For OBI/eBPF, grant only capabilities required by enabled modes and document any use of powerful capabilities.
+
+## Resource-exhaustion controls
+
+- Set workload CPU and memory requests and limits.
+- Put the memory limiter early in pipelines.
+- Bound exporter queues and retry duration.
+- Filter telemetry that has no operational value.
+- Control metric and log cardinality.
+- Rate-limit or isolate untrusted senders.
+- Alert on refusal, queue saturation, export failure, CPU, memory, disk, and restart signals.
+
+Scaling does not protect a saturated backend and can amplify a denial-of-service condition. Verify the constrained component before scaling.
+
+## Context and baggage boundaries
+
+- Treat incoming trace context as untrusted unless the source is authenticated and authorized.
+- Define whether external trace context is accepted, replaced, or sanitized.
+- Prevent internal trace identifiers or baggage from being forwarded to untrusted external services when disclosure is unacceptable.
+- Never store credentials, API keys, session tokens, or personal data in baggage.
+- Remember that baggage has no built-in guarantee that a value originated from a trusted service.
+
+## Security review checklist
+
+1. Map data sources, Collector tiers, destinations, and trust boundaries.
+2. Inventory listeners, protocols, addresses, ports, and administrative endpoints.
+3. Verify TLS, authentication, and authorization for each network hop.
+4. Inspect configuration and secret delivery.
+5. Inventory attributes, log bodies, baggage, and transformed data for sensitivity.
+6. Review filtering, redaction, and failure behavior.
+7. Review filesystem, RBAC, container, and kernel privileges.
+8. Review resource limits, queue bounds, and abuse controls.
+9. Verify internal telemetry and security-alert ownership.
+10. Check current CVEs and advisories for deployed components and versions.
+
+## Official sources
+
+- [OpenTelemetry security](https://opentelemetry.io/docs/security/)
+- [Collector configuration security](https://opentelemetry.io/docs/security/config-best-practices/)
+- [Collector hosting security](https://opentelemetry.io/docs/security/hosting-best-practices/)
+- [Handling sensitive data](https://opentelemetry.io/docs/security/handling-sensitive-data/)
+- [OpenTelemetry CVEs](https://opentelemetry.io/docs/security/cve/)
+- [Context propagation security](https://opentelemetry.io/docs/concepts/context-propagation/#security-best-practices)
+- [Baggage security considerations](https://opentelemetry.io/docs/concepts/signals/baggage/#baggage-security-considerations)

package/skills/neo-opentelemetry/references/signals-and-sampling.md

@@ -0,0 +1,113 @@
+# Signals and Sampling
+
+Use this reference to select signals, reason about correlation, and evaluate sampling. Signal maturity and feature support can change; verify current status before making version-dependent claims.
+
+## Signal selection
+
+| Signal | Primary question | Operational strengths | Important limitations |
+| --- | --- | --- | --- |
+| Traces | How did one request travel through the system? | Causality, dependency paths, per-request latency, error localization | Volume can be high; incomplete propagation fragments traces |
+| Metrics | What is happening in aggregate over time? | Alerting, trends, capacity, SLI/SLO measurement | Aggregation loses individual-event detail; dimensions can create high cardinality |
+| Logs | What discrete event occurred? | Detailed event records and existing operational workflows | Unstructured records are costly to normalize; correlation requires context |
+| Baggage | What request-scoped context must be available downstream? | Carries selected context across service boundaries | Propagates broadly, is not automatically a signal attribute, and has security risks |
+| Profiles | Where are CPU, memory, or other resources being consumed? | Resource bottlenecks and correlation with slow requests or resource spikes | Availability, status, and supported profile types depend on current tooling |
+
+Do not replace one signal with another merely because they share attributes. Prefer correlation through stable resource identity and trace context.
+
+## Traces
+
+A trace represents the path of a request and contains one or more spans. A span represents one unit of work and can carry timing, status, attributes, events, and links. Parent-child relationships describe causal or nested work.
+
+Review trace quality by checking:
+
+- Root and child span boundaries reflect meaningful operations.
+- Trace and parent identifiers remain continuous across boundaries.
+- Attributes follow semantic conventions and avoid sensitive or unbounded values.
+- Error state and latency are represented consistently enough for sampling and analysis.
+- Resource identity distinguishes services and instances.
+
+## Metrics
+
+A metric represents measurements aggregated over time. Operationally, distinguish:
+
+- Additive changes from current-state values.
+- Monotonic values from values that may rise or fall.
+- Cumulative from delta temporality.
+- Metric identity from attribute dimensions.
+
+Cardinality is the number of distinct time series produced by the combination of metric identity and attributes. User IDs, request IDs, raw URLs, and other unbounded values can make a metric operationally expensive or unusable. Prefer bounded dimensions that support an explicit operational question.
+
+When multiple Collector instances handle the same metric stream, preserve a globally unique writer identity and avoid duplicate writers that can create gaps, jumps, or out-of-order samples.
+
+## Logs
+
+OpenTelemetry can receive, normalize, correlate, process, and export existing logs. Structured logs have a stable schema or typed fields; JSON encoding alone does not guarantee structure. Semistructured and unstructured logs usually need parsing and normalization before reliable analysis.
+
+Operational priorities:
+
+1. Preserve event time and observed time when both are available.
+2. Add resource identity at collection time when the source does not provide it.
+3. Correlate logs with trace and span identifiers where supported.
+4. Normalize schemas before downstream rules depend on them.
+5. Filter or redact sensitive fields before export.
+
+Language logging bridges and application logging code are outside this skill.
+
+## Baggage
+
+Baggage is propagated contextual data, separate from span, metric, and log attributes. A baggage item is not automatically copied into telemetry attributes.
+
+Use baggage only when downstream components genuinely need request-scoped context. Never place credentials, API keys, session tokens, personal information, or other sensitive data in baggage. Define trust-boundary rules for accepting and forwarding baggage because it can leave the controlled network through automatic propagation.
+
+## Profiles
+
+Profiles contain samples and metadata describing resource consumption over time. They can complement:
+
+- Metrics by explaining a CPU or memory spike.
+- Traces by locating resource consumption associated with a slow request.
+- Logs by connecting a failure event to resource pressure.
+
+Keep profile collection details out of recommendations unless current official support has been verified for the target environment.
+
+## Sampling
+
+Sampling reduces trace volume by retaining a representative subset. Filtering and aggregation may also reduce data, but they do not automatically preserve representativeness.
+
+### Head sampling
+
+Head sampling decides early without examining the complete trace. It is comparatively simple and efficient, but cannot reliably retain every trace that later becomes slow or erroneous.
+
+Use head sampling when an early, consistent probability decision satisfies the observability goal and the lost late-trace information is acceptable.
+
+### Tail sampling
+
+Tail sampling decides after receiving all or most spans in a trace. It can retain traces based on whole-trace criteria such as errors, latency, attributes, or service-specific policy.
+
+Tail sampling is stateful and operationally expensive. It requires:
+
+- Enough memory and decision time to retain spans awaiting a decision.
+- Routing that sends every span for a trace to the same sampling instance.
+- Monitoring for dropped spans, late spans, decision-cache pressure, and uneven routing.
+- Reassessment as traffic and service behavior change.
+
+For multiple gateways, trace-ID-aware routing is necessary but does not remove every scaling caveat. Prefer a single adequately sized tail-sampling gateway until the need for a distributed design and its consistency strategy are demonstrated.
+
+### Sampling decision checklist
+
+1. Identify the cost or capacity problem sampling must solve.
+2. State what information may be lost and whether regulation permits dropping it.
+3. Measure trace volume and traffic variation by service.
+4. Define required retention rules for errors, latency, or business-critical traffic.
+5. Choose head sampling unless whole-trace evidence is required.
+6. If using tail sampling, design trace-affine routing and capacity before enabling it.
+7. Validate the retained population and monitor sampling infrastructure.
+
+## Official sources
+
+- [Signals](https://opentelemetry.io/docs/concepts/signals/)
+- [Traces](https://opentelemetry.io/docs/concepts/signals/traces/)
+- [Metrics](https://opentelemetry.io/docs/concepts/signals/metrics/)
+- [Logs](https://opentelemetry.io/docs/concepts/signals/logs/)
+- [Baggage](https://opentelemetry.io/docs/concepts/signals/baggage/)
+- [Profiles](https://opentelemetry.io/docs/concepts/signals/profiles/)
+- [Sampling](https://opentelemetry.io/docs/concepts/sampling/)

package/skills/neo-opentelemetry/references/sources-and-scope.md

@@ -0,0 +1,60 @@
+# Sources, Scope, and Currency
+
+## Source snapshot
+
+This skill was derived from the English OpenTelemetry documentation stored at:
+
+- Repository: `https://github.com/open-telemetry/opentelemetry.io`
+- Source subtree: `content/en/docs`
+- Revision: `b18eb4d01fab9be2c5c22b1aaafdeb23ba97e3d4`
+- Revision timestamp: `2026-07-17T02:20:14Z`
+- Documentation root: `https://opentelemetry.io/docs/`
+
+The source subtree contained 423 Markdown files at generation time. The material was curated and rewritten rather than copied wholesale.
+
+## Included source areas
+
+- `what-is-opentelemetry.md`
+- Non-programming material from `concepts/`
+- Collector architecture, components, configuration, installation, deployment, management, internal telemetry, resiliency, scaling, transformation, troubleshooting, distributions, benchmarks, and registry material
+- Operational material from `getting-started/ops.md`
+- Prometheus interoperability and migration concepts from `compatibility/`
+- Non-programming platform blueprints and reference-implementation lessons from `guidance/`
+- Kubernetes, FaaS automatic instrumentation, and operational platform material from `platforms/`
+- Security and sensitive-data material from `security/`
+- Zero-code and OBI operational material from `zero-code/`
+- Non-programming demo architecture or operational lessons only when they clarify an included concept
+
+## Excluded source areas
+
+- All language API and SDK instructions under `languages/`
+- Code-based instrumentation and language-library integration
+- Developer getting-started and reference-application implementation material
+- Collector source builds, Collector Builder, and custom component development under `collector/extend/`
+- Manual FaaS instrumentation
+- Demo service source, development, tests, and manual span examples
+- Contribution workflow and website-development documentation
+- API, SDK, data-model implementation, and programming-oriented specification pages
+- Source-code snippets in Java, C#, Go, JavaScript, TypeScript, Python, PHP, Ruby, Rust, Swift, C++, and other programming languages
+
+Mixed pages were reduced to concepts, declarative YAML or JSON configuration, environment variables, and operational shell, Docker, cloud, or Kubernetes commands. High-level references to an API or SDK may remain only when needed to state a system boundary or migration limitation; this skill never provides their programming interface.
+
+## Currency policy
+
+The snapshot is evidence for the content as of its revision. It is not evidence that a version, status, default, component, platform matrix, security advisory, image, package, or command remains current.
+
+Verify against official sources before answering time-sensitive questions about:
+
+- Collector, Operator, Helm, OBI, FaaS layer, or semantic-convention versions.
+- Signal or component maturity.
+- Component availability in a distribution.
+- Runtime, platform, kernel, architecture, or protocol support.
+- Default endpoints, limits, queue behavior, or feature gates.
+- CVEs, security advisories, and mitigations.
+- Migration shims and compatibility guarantees.
+
+If current verification is unavailable, state:
+
+1. The claim is based on revision `b18eb4d01fab9be2c5c22b1aaafdeb23ba97e3d4`.
+2. Current status cannot be confirmed.
+3. The official page the user should verify.