@moon791017/neo-skills 1.1.11 → 1.1.13

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)