Fediversity

Feature Specification: Resource otel

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/resources/otel/ and of the windmill and netbox components at 093e68b6f, pull requests #1184, #1205 and #1206.

User Scenarios & Testing (mandatory)

The otel resource lets an application send OpenTelemetry signals to the collector of its deployment. The policy holds the OTLP endpoint. For each enabled request, the policy gives the endpoint to the node under the name of the consumer. The telemetry module of each application reads that entry and configures its services. The shared resource rules are in the resource family spec.

User Story 1 - Send telemetry from an application (Priority: P1)

An operator of the hosting provider wants traces and metrics from windmill and netbox. Each component requests otel under its consumer name and imports its own telemetry module. That module points the services at the endpoint, sets the protocol, and names the service and its resource attributes. For netbox, the module also runs the web and worker processes under automatic OpenTelemetry instrumentation.

Why this priority: telemetry from the platform services is the purpose of the resource.

Independent Test: unit tests that the endpoint of the policy reaches the services of windmill and of netbox, and a test of the wiring.

Acceptance Scenarios:

  1. Given a policy with an endpoint, When the windmill or the netbox node evaluates, Then the services of that application export to that endpoint.

User Story 2 - Find the collector of the deployment (Priority: P1)

A node of the deployment provides otel. The setup sets the endpoint, as a default, to the collector on that node. The traffic uses plain HTTP on the internal network. An environment can replace the endpoint.

Why this priority: without an endpoint, no application sends telemetry.

Independent Test: a unit test that the endpoint defaults to the collector of the group.

Acceptance Scenarios:

  1. Given a deployment with a node that provides otel and no override, When an application node evaluates, Then the endpoint is the collector on that node.

User Story 3 - Keep telemetry off (Priority: P2)

A deployment has no collector, or an environment clears the endpoint. The policy then gives nothing to the node, and no service gets telemetry settings.

Why this priority: an application must not send signals to an address that does not exist.

Independent Test: a unit test with a cleared endpoint.

Acceptance Scenarios:

  1. Given no endpoint, When the windmill node evaluates, Then its services have no export endpoint.

Edge Cases

  • When no request on a node is enabled, the policy gives nothing, also when an endpoint is set.
  • The entry applies to one consumer. An application on the same node that imports a telemetry module but does not request the resource gets no telemetry settings.

Requirements (mandatory)

Functional Requirements

  • FR-001: The request MUST accept an enable flag (off by default) and a consumer name. The request MUST contain only data, so that it can be serialized to JSON.
  • FR-002: The policy MUST accept an endpoint or no endpoint (the default).
  • FR-003: Without an endpoint, the policy MUST give nothing to the node.
  • FR-004: With an endpoint, the policy MUST give the node, for each enabled request, the endpoint under the consumer name of that request.
  • FR-005: The setup MUST default the endpoint to the collector of the deployment when a node of the deployment provides otel, and to no endpoint otherwise.
  • FR-006: The setup MUST make each node import the output of the policy.

Key Entities

  • Endpoint: the OTLP HTTP endpoint of the collector.
  • Consumer endpoint entry: the endpoint on the application node, keyed by consumer name. It is absent when the request is not enabled or the policy has no endpoint. The telemetry module of each application reads it.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: the unit tests of the resource and the test that requests contain only data pass.

Assumptions

  • The collector listens for OTLP over HTTP on a fixed port. The default endpoint of the setup must use the same port as the collector.
  • The internal network is trusted, so the signals travel without TLS.

Known Deviations

None.