Add DHCP semantic conventions for DHCPv4 and DHCPv6

.chloggen/dhcp-semantic-conventions.yaml

@@ -0,0 +1,26 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: dhcp
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add semantic conventions for DHCP (Dynamic Host Configuration Protocol) covering DHCPv4 and DHCPv6.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: []
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Includes attributes for DHCP message types, client/server identifiers, lease information,
+  DHCPv4 fields and options, DHCPv6 fields and options, and relay agent information.
+  Defines spans for client and server instrumentation, metrics for request duration,
+  lease tracking, and pool utilization.

.github/CODEOWNERS

@@ -115,6 +115,8 @@
 # /model/process/                 is defined in system section
 /model/tls/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
 /model/user/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+/docs/dhcp/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
+/model/dhcp/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
 
 # CICD semantic conventions
 /docs/cicd/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers

docs/dhcp/README.md

@@ -0,0 +1,19 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: DHCP
+--->
+
+# Semantic Conventions for DHCP
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for DHCP (Dynamic Host Configuration
+Protocol) instrumentation, covering both DHCPv4
+([RFC 2131](https://www.rfc-editor.org/rfc/rfc2131)/[RFC 2132](https://www.rfc-editor.org/rfc/rfc2132))
+and DHCPv6 ([RFC 8415](https://www.rfc-editor.org/rfc/rfc8415)).
+
+Semantic conventions for DHCP are defined for the following signals:
+
+- [DHCP Spans](dhcp-spans.md): Semantic Conventions for DHCP client and server *spans*.
+- [DHCP Metrics](dhcp-metrics.md): Semantic Conventions for DHCP *metrics*.
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/dhcp/dhcp-metrics.md

@@ -0,0 +1,102 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Metrics
+--->
+
+# Semantic Conventions for DHCP Metrics
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for DHCP metrics, covering client,
+server, and relay agent instrumentation.
+
+<!-- toc -->
+
+- [Client Metrics](#client-metrics)
+  - [Metric: `dhcp.client.request.duration`](#metric-dhcpclientrequestduration)
+  - [Metric: `dhcp.client.lease.duration`](#metric-dhcpclientleaseduration)
+- [Server Metrics](#server-metrics)
+  - [Metric: `dhcp.server.request.duration`](#metric-dhcpserverrequestduration)
+  - [Metric: `dhcp.server.pool.usage`](#metric-dhcpserverpoolusage)
+  - [Metric: `dhcp.server.pool.limit`](#metric-dhcpserverpoollimit)
+  - [Metric: `dhcp.server.pool.utilization`](#metric-dhcpserverpoolutilization)
+  - [Metric: `dhcp.server.leases.active`](#metric-dhcpserverleasesactive)
+- [Relay Metrics](#relay-metrics)
+  - [Metric: `dhcp.relay.request.duration`](#metric-dhcprelayrequestduration)
+
+<!-- tocstop -->
+
+## Client Metrics
+
+### Metric: `dhcp.client.request.duration`
+
+This metric measures the duration of DHCP client requests.
+
+This metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.53.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
+
+<!-- semconv metric.dhcp.client.request.duration -->
+<!-- endsemconv -->
+
+### Metric: `dhcp.client.lease.duration`
+
+This metric tracks the time remaining on the current lease.
+
+<!-- semconv metric.dhcp.client.lease.duration -->
+<!-- endsemconv -->
+
+## Server Metrics
+
+### Metric: `dhcp.server.request.duration`
+
+This metric measures server-side request processing duration.
+
+This metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.53.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
+
+<!-- semconv metric.dhcp.server.request.duration -->
+<!-- endsemconv -->
+
+### Metric: `dhcp.server.pool.usage`
+
+This metric tracks address pool utilization (number of addresses currently leased).
+
+<!-- semconv metric.dhcp.server.pool.usage -->
+<!-- endsemconv -->
+
+### Metric: `dhcp.server.pool.limit`
+
+This metric reports the total capacity of an address pool.
+
+<!-- semconv metric.dhcp.server.pool.limit -->
+<!-- endsemconv -->
+
+### Metric: `dhcp.server.pool.utilization`
+
+This metric reports pool utilization as a ratio (0.0-1.0).
+
+<!-- semconv metric.dhcp.server.pool.utilization -->
+<!-- endsemconv -->
+
+### Metric: `dhcp.server.leases.active`
+
+This metric tracks the number of active leases.
+
+<!-- semconv metric.dhcp.server.leases.active -->
+<!-- endsemconv -->
+
+## Relay Metrics
+
+### Metric: `dhcp.relay.request.duration`
+
+This metric measures relay processing latency.
+
+This metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.53.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
+
+<!-- semconv metric.dhcp.relay.request.duration -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/dhcp/dhcp-spans.md

@@ -0,0 +1,84 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Spans
+--->
+
+# Semantic Conventions for DHCP Spans
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for DHCP spans, covering both
+client and server instrumentation.
+
+<!-- toc -->
+
+- [Span Name](#span-name)
+- [Span Kind](#span-kind)
+- [Client Spans](#client-spans)
+- [Server Spans](#server-spans)
+- [Span Status](#span-status)
+- [Span Events](#span-events)
+
+<!-- tocstop -->
+
+## Span Name
+
+DHCP span names SHOULD follow the pattern: `DHCP {message_type}`
+
+The `{message_type}` MUST be the value of `dhcp.message.type`.
+
+**Examples:**
+
+- `DHCP DISCOVER`
+- `DHCP OFFER`
+- `DHCP SOLICIT`
+- `DHCP ADVERTISE`
+
+## Span Kind
+
+| Role                             | Span Kind  |
+| -------------------------------- | ---------- |
+| DHCP client sending request      | `CLIENT`   |
+| DHCP server processing request   | `SERVER`   |
+| DHCP relay agent forwarding      | `INTERNAL` |
+
+## Client Spans
+
+Client instrumentations SHOULD create a span for each DHCP message sent.
+
+<!-- semconv dhcp.client -->
+<!-- endsemconv -->
+
+## Server Spans
+
+Server instrumentations SHOULD create a span for each DHCP message processed.
+
+<!-- semconv dhcp.server -->
+<!-- endsemconv -->
+
+## Span Status
+
+Instrumentation SHOULD set span status as follows:
+
+| Condition                                      | Span Status                    |
+| ---------------------------------------------- | ------------------------------ |
+| Successful response (ACK, REPLY with success)  | Leave unset (defaults to `OK`) |
+| NAK received/sent                              | `ERROR`                        |
+| Timeout waiting for response                   | `ERROR`                        |
+| Address declined (in use)                      | `ERROR`                        |
+| Processing error                               | `ERROR`                        |
+
+When status is `ERROR`, the `error.type` attribute SHOULD be populated.
+
+## Span Events
+
+The following events MAY be recorded on DHCP spans:
+
+| Event Name               | Description                 |
+| ------------------------ | --------------------------- |
+| `dhcp.message.sent`      | Message transmitted         |
+| `dhcp.message.received`  | Message received            |
+| `dhcp.address.allocated` | Address assigned to client  |
+| `dhcp.address.released`  | Address released by client  |
+| `dhcp.lease.expired`     | Lease expiration detected   |
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status