diff --git a/.chloggen/dhcp-semantic-conventions.yaml b/.chloggen/dhcp-semantic-conventions.yaml new file mode 100644 index 0000000000..9aab88aca7 --- /dev/null +++ b/.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. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4f565db24f..b49a13388a 100644 --- a/.github/CODEOWNERS +++ b/.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 diff --git a/docs/dhcp/README.md b/docs/dhcp/README.md new file mode 100644 index 0000000000..f1ca7f40cb --- /dev/null +++ b/docs/dhcp/README.md @@ -0,0 +1,19 @@ + + +# 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 diff --git a/docs/dhcp/dhcp-metrics.md b/docs/dhcp/dhcp-metrics.md new file mode 100644 index 0000000000..fa9d1139e8 --- /dev/null +++ b/docs/dhcp/dhcp-metrics.md @@ -0,0 +1,102 @@ + + +# Semantic Conventions for DHCP Metrics + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for DHCP metrics, covering client, +server, and relay agent instrumentation. + + + +- [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) + + + +## 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 ]`. + + + + +### Metric: `dhcp.client.lease.duration` + +This metric tracks the time remaining on the current lease. + + + + +## 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 ]`. + + + + +### Metric: `dhcp.server.pool.usage` + +This metric tracks address pool utilization (number of addresses currently leased). + + + + +### Metric: `dhcp.server.pool.limit` + +This metric reports the total capacity of an address pool. + + + + +### Metric: `dhcp.server.pool.utilization` + +This metric reports pool utilization as a ratio (0.0-1.0). + + + + +### Metric: `dhcp.server.leases.active` + +This metric tracks the number of active leases. + + + + +## 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 ]`. + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/dhcp/dhcp-spans.md b/docs/dhcp/dhcp-spans.md new file mode 100644 index 0000000000..4007d5b609 --- /dev/null +++ b/docs/dhcp/dhcp-spans.md @@ -0,0 +1,84 @@ + + +# Semantic Conventions for DHCP Spans + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for DHCP spans, covering both +client and server instrumentation. + + + +- [Span Name](#span-name) +- [Span Kind](#span-kind) +- [Client Spans](#client-spans) +- [Server Spans](#server-spans) +- [Span Status](#span-status) +- [Span Events](#span-events) + + + +## 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. + + + + +## Server Spans + +Server instrumentations SHOULD create a span for each DHCP message processed. + + + + +## 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 diff --git a/model/dhcp/metrics.yaml b/model/dhcp/metrics.yaml new file mode 100644 index 0000000000..f6490100cd --- /dev/null +++ b/model/dhcp/metrics.yaml @@ -0,0 +1,159 @@ +groups: + # Client Metrics + - id: metric.dhcp.client.request.duration + type: metric + metric_name: dhcp.client.request.duration + stability: development + brief: Duration of DHCP client request operations. + instrument: histogram + unit: "s" + attributes: + - ref: dhcp.message.type + requirement_level: required + brief: The request message type. + - ref: dhcp.response.status_code + requirement_level: recommended + brief: Result status. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + - ref: network.interface.name + requirement_level: recommended + brief: Interface name. + - ref: server.address + requirement_level: recommended + brief: Server that responded. + - ref: error.type + requirement_level: + conditionally_required: Required if request failed. + brief: Error classification when request fails. + + - id: metric.dhcp.client.lease.duration + type: metric + metric_name: dhcp.client.lease.duration + stability: development + brief: Time remaining on current lease. + instrument: gauge + unit: "s" + attributes: + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + - ref: network.interface.name + requirement_level: required + brief: Interface with lease. + - ref: dhcp.v4.yiaddr + requirement_level: + conditionally_required: Required for DHCPv4. + brief: Assigned IPv4 address. + - ref: dhcp.v6.option.ia_address + requirement_level: + conditionally_required: Required for DHCPv6. + brief: Assigned IPv6 address. + + # Server Metrics + - id: metric.dhcp.server.request.duration + type: metric + metric_name: dhcp.server.request.duration + stability: development + brief: Duration of DHCP server request processing. + instrument: histogram + unit: "s" + attributes: + - ref: dhcp.message.type + requirement_level: required + brief: The response message type. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + - ref: error.type + requirement_level: + conditionally_required: Required if processing failed. + brief: Error classification when processing fails. + + - id: metric.dhcp.server.pool.usage + type: metric + metric_name: dhcp.server.pool.usage + stability: development + brief: Number of addresses currently leased from pool. + instrument: gauge + unit: "{address}" + attributes: + - ref: dhcp.server.pool.name + requirement_level: required + brief: Pool identifier. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + + - id: metric.dhcp.server.pool.limit + type: metric + metric_name: dhcp.server.pool.limit + stability: development + brief: Total addresses available in pool. + instrument: gauge + unit: "{address}" + attributes: + - ref: dhcp.server.pool.name + requirement_level: required + brief: Pool identifier. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + + - id: metric.dhcp.server.pool.utilization + type: metric + metric_name: dhcp.server.pool.utilization + stability: development + brief: Ratio of used to total addresses (0.0-1.0). + instrument: gauge + unit: "1" + attributes: + - ref: dhcp.server.pool.name + requirement_level: required + brief: Pool identifier. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + + - id: metric.dhcp.server.leases.active + type: metric + metric_name: dhcp.server.leases.active + stability: development + brief: Current count of active leases. + instrument: updowncounter + unit: "{lease}" + attributes: + - ref: dhcp.server.pool.name + requirement_level: recommended + brief: Pool name if applicable. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + + # Relay Metrics + - id: metric.dhcp.relay.request.duration + type: metric + metric_name: dhcp.relay.request.duration + stability: development + brief: Duration of relay forwarding. + instrument: histogram + unit: "s" + attributes: + - ref: dhcp.message.type + requirement_level: required + brief: Message type forwarded. + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + - ref: dhcp.relay.direction + requirement_level: required + brief: "`client_to_server` or `server_to_client`." diff --git a/model/dhcp/registry.yaml b/model/dhcp/registry.yaml new file mode 100644 index 0000000000..8f9f09b37e --- /dev/null +++ b/model/dhcp/registry.yaml @@ -0,0 +1,563 @@ +groups: + # Common DHCP Attributes + - id: registry.dhcp + type: attribute_group + display_name: DHCP Attributes + brief: > + This document defines attributes for DHCP (Dynamic Host Configuration Protocol) + instrumentation, covering both DHCPv4 (RFC 2131/2132) and DHCPv6 (RFC 8415). + attributes: + - id: dhcp.message.type + type: + members: + # DHCPv4 message types + - id: discover + value: "DISCOVER" + brief: Client broadcast to locate servers. + stability: development + - id: offer + value: "OFFER" + brief: Server response with configuration offer. + stability: development + - id: request + value: "REQUEST" + brief: Client requests offered configuration. + stability: development + - id: decline + value: "DECLINE" + brief: Client indicates address already in use. + stability: development + - id: ack + value: "ACK" + brief: Server acknowledges request. + stability: development + - id: nak + value: "NAK" + brief: Server negative acknowledgment. + stability: development + - id: release + value: "RELEASE" + brief: Client releases address. + stability: development + - id: inform + value: "INFORM" + brief: Client requests configuration only. + stability: development + - id: forcerenew + value: "FORCERENEW" + brief: Server forces client renewal. + stability: development + - id: leasequery + value: "LEASEQUERY" + brief: Lease query request. + stability: development + - id: leaseunassigned + value: "LEASEUNASSIGNED" + brief: "Lease query: unassigned." + stability: development + - id: leaseunknown + value: "LEASEUNKNOWN" + brief: "Lease query: unknown." + stability: development + - id: leaseactive + value: "LEASEACTIVE" + brief: "Lease query: active." + stability: development + - id: bulkleasequery + value: "BULKLEASEQUERY" + brief: Bulk lease query. + stability: development + - id: leasequerydone + value: "LEASEQUERYDONE" + brief: Lease query complete. + stability: development + # DHCPv6 message types + - id: solicit + value: "SOLICIT" + brief: Client locates servers. + stability: development + - id: advertise + value: "ADVERTISE" + brief: Server indicates availability. + stability: development + - id: confirm + value: "CONFIRM" + brief: Client verifies address. + stability: development + - id: renew + value: "RENEW" + brief: Client extends lease with original server. + stability: development + - id: rebind + value: "REBIND" + brief: Client seeks renewal from any server. + stability: development + - id: reply + value: "REPLY" + brief: Server response. + stability: development + - id: reconfigure + value: "RECONFIGURE" + brief: Server initiates reconfiguration. + stability: development + - id: information_request + value: "INFORMATION_REQUEST" + brief: Client requests config without lease. + stability: development + - id: relay_forw + value: "RELAY_FORW" + brief: Relay forwards to server. + stability: development + - id: relay_repl + value: "RELAY_REPL" + brief: Server replies via relay. + stability: development + stability: development + brief: The DHCP message type name. + examples: ["DISCOVER", "OFFER", "SOLICIT", "ADVERTISE"] + + - id: dhcp.operation.name + type: string + stability: development + brief: The name of the operation being performed. + examples: ["lease_acquisition", "renewal", "release"] + + - id: dhcp.request.id + type: string + stability: development + brief: Transaction ID (xid) for request-response correlation. + examples: ["0x3d1d2f8a"] + + - id: dhcp.response.status_code + type: + members: + - id: success + value: "success" + brief: Operation successful. + stability: development + - id: unspec_fail + value: "unspec_fail" + brief: Unspecified failure. + stability: development + - id: no_addrs_avail + value: "no_addrs_avail" + brief: No addresses available. + stability: development + - id: no_binding + value: "no_binding" + brief: No binding exists. + stability: development + - id: not_on_link + value: "not_on_link" + brief: Address not appropriate for link. + stability: development + - id: use_multicast + value: "use_multicast" + brief: Server wants client to use multicast. + stability: development + - id: no_prefix_avail + value: "no_prefix_avail" + brief: No prefixes available. + stability: development + - id: nak + value: "nak" + brief: Server negative acknowledgment (DHCPv4). + stability: development + stability: development + brief: The status/result of the DHCP operation. + examples: ["success", "nak", "no_addrs_avail"] + + - id: dhcp.client.identifier + type: string + stability: development + brief: Client identifier (option 61 for DHCPv4, DUID for DHCPv6). + examples: ["01:aa:bb:cc:dd:ee:ff"] + + - id: dhcp.server.identifier + type: string + stability: development + brief: Server identifier (option 54 for DHCPv4, DUID for DHCPv6). + examples: ["192.168.1.1"] + + - id: dhcp.lease.duration + type: int + stability: development + brief: Lease time in seconds. + examples: [86400, 3600] + + - id: dhcp.server.pool.name + type: string + stability: development + brief: Pool identifier. + examples: ["lan-pool", "guest-pool"] + + - id: dhcp.relay.direction + type: + members: + - id: client_to_server + value: "client_to_server" + brief: Message forwarded from client to server. + stability: development + - id: server_to_client + value: "server_to_client" + brief: Message forwarded from server to client. + stability: development + stability: development + brief: Direction of relay forwarding. + examples: ["client_to_server", "server_to_client"] + + # DHCPv4 Attributes + - id: registry.dhcp.v4 + type: attribute_group + display_name: DHCPv4 Attributes + brief: > + Attributes specific to DHCPv4 protocol fields. + attributes: + - id: dhcp.v4.op + type: + members: + - id: bootrequest + value: "BOOTREQUEST" + brief: Request from client to server. + stability: development + - id: bootreply + value: "BOOTREPLY" + brief: Reply from server to client. + stability: development + stability: development + brief: Message operation type. + examples: ["BOOTREQUEST", "BOOTREPLY"] + + - id: dhcp.v4.htype + type: int + stability: development + brief: Hardware address type per RFC 1700. `1` for Ethernet. + examples: [1, 6] + + - id: dhcp.v4.hops + type: int + stability: development + brief: Relay agent hop count. + examples: [0, 1, 2] + + - id: dhcp.v4.secs + type: int + stability: development + brief: Seconds elapsed since client began acquisition. + examples: [0, 5, 30] + + - id: dhcp.v4.flags.broadcast + type: boolean + stability: development + brief: Whether the broadcast flag is set. + examples: [true, false] + + - id: dhcp.v4.ciaddr + type: string + stability: development + brief: Client IP address (set when client is bound/renewing). + examples: ["192.168.1.100"] + + - id: dhcp.v4.yiaddr + type: string + stability: development + brief: '"Your" IP address (offered/assigned address).' + examples: ["192.168.1.100"] + + - id: dhcp.v4.siaddr + type: string + stability: development + brief: Next server IP address (TFTP server). + examples: ["192.168.1.1"] + + - id: dhcp.v4.giaddr + type: string + stability: development + brief: Relay agent IP address. + examples: ["192.168.1.254"] + + - id: dhcp.v4.chaddr + type: string + stability: development + brief: Client hardware address (MAC address). + examples: ["aa:bb:cc:dd:ee:ff"] + + - id: dhcp.v4.sname + type: string + stability: development + brief: Server hostname. + examples: ["dhcp-server-1"] + + - id: dhcp.v4.file + type: string + stability: development + brief: Boot filename. + examples: ["pxelinux.0"] + + # DHCPv4 Option Attributes + - id: registry.dhcp.v4.option + type: attribute_group + display_name: DHCPv4 Option Attributes + brief: > + Attributes for common DHCPv4 options. + attributes: + - id: dhcp.v4.option.subnet_mask + type: string + stability: development + brief: Subnet mask (option 1). + examples: ["255.255.255.0"] + + - id: dhcp.v4.option.router + type: string[] + stability: development + brief: Default gateway address(es) (option 3). + examples: [["192.168.1.1"]] + + - id: dhcp.v4.option.dns_server + type: string[] + stability: development + brief: DNS server address(es) (option 6). + examples: [["8.8.8.8", "8.8.4.4"]] + + - id: dhcp.v4.option.hostname + type: string + stability: development + brief: Client hostname (option 12). + examples: ["workstation-01"] + + - id: dhcp.v4.option.domain_name + type: string + stability: development + brief: DNS domain name (option 15). + examples: ["example.com"] + + - id: dhcp.v4.option.broadcast_address + type: string + stability: development + brief: Broadcast address (option 28). + examples: ["192.168.1.255"] + + - id: dhcp.v4.option.ntp_server + type: string[] + stability: development + brief: NTP server address(es) (option 42). + examples: [["time.example.com"]] + + - id: dhcp.v4.option.requested_ip + type: string + stability: development + brief: Requested IP address (option 50). + examples: ["192.168.1.100"] + + - id: dhcp.v4.option.lease_time + type: int + stability: development + brief: Lease duration in seconds (option 51). + examples: [86400] + + - id: dhcp.v4.option.renewal_time + type: int + stability: development + brief: T1 renewal time in seconds (option 58). + examples: [43200] + + - id: dhcp.v4.option.rebinding_time + type: int + stability: development + brief: T2 rebinding time in seconds (option 59). + examples: [75600] + + - id: dhcp.v4.option.vendor_class + type: string + stability: development + brief: Vendor class identifier (option 60). + examples: ["MSFT 5.0"] + + - id: dhcp.v4.option.tftp_server + type: string + stability: development + brief: TFTP server name (option 66). + examples: ["tftp.example.com"] + + - id: dhcp.v4.option.bootfile + type: string + stability: development + brief: Boot filename (option 67). + examples: ["pxelinux.0"] + + - id: dhcp.v4.option.domain_search + type: string[] + stability: development + brief: DNS search domain list (option 119). + examples: [["example.com", "corp.example.com"]] + + # DHCPv4 Relay Attributes + - id: registry.dhcp.v4.relay + type: attribute_group + display_name: DHCPv4 Relay Attributes + brief: > + Attributes for DHCPv4 relay agent information (option 82). + attributes: + - id: dhcp.v4.relay.circuit_id + type: string + stability: development + brief: "Option 82 sub-option 1: Circuit identifier." + examples: ["ge-0/0/1.100"] + + - id: dhcp.v4.relay.remote_id + type: string + stability: development + brief: "Option 82 sub-option 2: Remote identifier." + examples: ["00:11:22:33:44:55"] + + - id: dhcp.v4.relay.subscriber_id + type: string + stability: development + brief: "Option 82 sub-option 6: Subscriber identifier." + examples: ["subscriber-001"] + + # DHCPv6 Attributes + - id: registry.dhcp.v6 + type: attribute_group + display_name: DHCPv6 Attributes + brief: > + Attributes specific to DHCPv6 protocol fields. + attributes: + - id: dhcp.v6.hop_count + type: int + stability: development + brief: Relay hop count. + examples: [0, 1] + + - id: dhcp.v6.link_address + type: string + stability: development + brief: Relay link address. + examples: ["2001:db8::1"] + + - id: dhcp.v6.peer_address + type: string + stability: development + brief: Relay peer address. + examples: ["fe80::1"] + + # DHCPv6 Option Attributes + - id: registry.dhcp.v6.option + type: attribute_group + display_name: DHCPv6 Option Attributes + brief: > + Attributes for common DHCPv6 options. + attributes: + - id: dhcp.v6.option.ia_address + type: string + stability: development + brief: Identity Association address (option 5). + examples: ["2001:db8::100"] + + - id: dhcp.v6.option.preference + type: int + stability: development + brief: Server preference value 0-255 (option 7). + examples: [255] + + - id: dhcp.v6.option.elapsed_time + type: int + stability: development + brief: Elapsed time in centiseconds (option 8). + examples: [100] + + - id: dhcp.v6.option.status_code + type: int + stability: development + brief: Status code (option 13). + examples: [0, 2] + + - id: dhcp.v6.option.status_message + type: string + stability: development + brief: Status message (option 13). + examples: ["Success"] + + - id: dhcp.v6.option.rapid_commit + type: boolean + stability: development + brief: Whether rapid commit is present (option 14). + examples: [true] + + - id: dhcp.v6.option.dns_server + type: string[] + stability: development + brief: DNS recursive server address(es) (option 23). + examples: [["2001:4860:4860::8888"]] + + - id: dhcp.v6.option.domain_search + type: string[] + stability: development + brief: Domain search list (option 24). + examples: [["example.com"]] + + - id: dhcp.v6.option.ia_prefix + type: string + stability: development + brief: Identity Association prefix (option 26). + examples: ["2001:db8::/48"] + + - id: dhcp.v6.option.fqdn + type: string + stability: development + brief: Client FQDN (option 39). + examples: ["host.example.com"] + + # DHCPv6 DUID Attributes + - id: registry.dhcp.v6.duid + type: attribute_group + display_name: DHCPv6 DUID Attributes + brief: > + Attributes for DHCPv6 DHCP Unique Identifier (DUID). + attributes: + - id: dhcp.v6.duid.type + type: + members: + - id: llt + value: "LLT" + brief: Link-layer address plus time. + stability: development + - id: en + value: "EN" + brief: Enterprise number. + stability: development + - id: ll + value: "LL" + brief: Link-layer address. + stability: development + - id: uuid + value: "UUID" + brief: Universally Unique Identifier. + stability: development + stability: development + brief: DUID type. + examples: ["LLT", "EN", "LL", "UUID"] + + - id: dhcp.v6.duid.hardware_type + type: int + stability: development + brief: Hardware type for LLT/LL DUIDs. + examples: [1] + + - id: dhcp.v6.duid.time + type: int + stability: development + brief: Time value for LLT (seconds since 2000-01-01). + examples: [789012345] + + - id: dhcp.v6.duid.enterprise_number + type: int + stability: development + brief: Enterprise number for EN DUIDs. + examples: [9] + + - id: dhcp.v6.duid.link_layer_address + type: string + stability: development + brief: Link-layer address. + examples: ["aa:bb:cc:dd:ee:ff"] diff --git a/model/dhcp/spans.yaml b/model/dhcp/spans.yaml new file mode 100644 index 0000000000..4f46eb8d7d --- /dev/null +++ b/model/dhcp/spans.yaml @@ -0,0 +1,181 @@ +groups: + # DHCP Client Spans + - id: dhcp.client + type: span + span_kind: client + stability: development + brief: > + Semantic conventions for DHCP client spans. Client instrumentations + SHOULD create a span for each DHCP message sent. + note: | + 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` + attributes: + - ref: dhcp.message.type + requirement_level: required + brief: The DHCP message type. + - ref: dhcp.request.id + requirement_level: required + brief: Transaction ID for correlation. + - ref: network.protocol.name + requirement_level: required + brief: MUST be `dhcp`. + examples: ["dhcp"] + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + - ref: dhcp.client.identifier + requirement_level: recommended + brief: Client identifier. + - ref: dhcp.v4.chaddr + requirement_level: + conditionally_required: Required for DHCPv4. + brief: Client hardware address. + - ref: dhcp.v4.option.requested_ip + requirement_level: + conditionally_required: Required in REQUEST when requesting specific IP. + brief: Requested IP address. + - ref: dhcp.server.identifier + requirement_level: + conditionally_required: Required in REQUEST, RELEASE, DECLINE. + brief: Server identifier. + - ref: network.interface.name + requirement_level: recommended + brief: Interface used. + - ref: server.address + requirement_level: recommended + brief: Target server address. + - ref: error.type + requirement_level: + conditionally_required: Required if operation fails. + brief: Error classification when operation fails. + + # DHCP Server Spans + - id: dhcp.server + type: span + span_kind: server + stability: development + brief: > + Semantic conventions for DHCP server spans. Server instrumentations + SHOULD create a span for each DHCP message processed. + note: | + DHCP span names SHOULD follow the pattern: `DHCP {message_type}` + + The `{message_type}` MUST be the value of `dhcp.message.type`. + + 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. + attributes: + - ref: dhcp.message.type + requirement_level: required + brief: The DHCP message type of response. + - ref: dhcp.request.id + requirement_level: required + brief: Transaction ID. + - ref: network.protocol.name + requirement_level: required + brief: MUST be `dhcp`. + examples: ["dhcp"] + - ref: network.protocol.version + requirement_level: required + brief: "`4` or `6`." + examples: ["4", "6"] + - ref: dhcp.client.identifier + requirement_level: recommended + brief: Client identifier from request. + - ref: dhcp.server.identifier + requirement_level: required + brief: Server identifier. + - ref: dhcp.v4.yiaddr + requirement_level: + conditionally_required: Required in OFFER, ACK for DHCPv4. + brief: Offered/assigned IP address. + - ref: dhcp.v6.option.ia_address + requirement_level: + conditionally_required: Required in ADVERTISE, REPLY for DHCPv6. + brief: Identity Association address. + - ref: dhcp.lease.duration + requirement_level: + conditionally_required: Required in OFFER, ACK, ADVERTISE, REPLY. + brief: Lease time in seconds. + - ref: dhcp.response.status_code + requirement_level: + conditionally_required: Required for NAK or error responses. + brief: Status/result of the DHCP operation. + - ref: dhcp.v4.giaddr + requirement_level: + conditionally_required: Required if request came via relay. + brief: Relay agent IP address. + - ref: network.peer.address + requirement_level: recommended + brief: Client or relay address. + - ref: error.type + requirement_level: + conditionally_required: Required if processing fails. + brief: Error classification when processing fails. + + # DHCP Span Events + - id: dhcp.message.sent + type: event + stability: development + brief: Event recorded when a DHCP message is transmitted. + attributes: + - ref: dhcp.message.type + requirement_level: required + + - id: dhcp.message.received + type: event + stability: development + brief: Event recorded when a DHCP message is received. + attributes: + - ref: dhcp.message.type + requirement_level: required + + - id: dhcp.address.allocated + type: event + stability: development + brief: Event recorded when an address is assigned to a client. + attributes: + - ref: dhcp.v4.yiaddr + requirement_level: + conditionally_required: Required for DHCPv4. + - ref: dhcp.v6.option.ia_address + requirement_level: + conditionally_required: Required for DHCPv6. + + - id: dhcp.address.released + type: event + stability: development + brief: Event recorded when an address is released by a client. + attributes: + - ref: dhcp.v4.ciaddr + requirement_level: + conditionally_required: Required for DHCPv4. + - ref: dhcp.v6.option.ia_address + requirement_level: + conditionally_required: Required for DHCPv6. + + - id: dhcp.lease.expired + type: event + stability: development + brief: Event recorded when a lease expiration is detected. + attributes: + - ref: dhcp.client.identifier + requirement_level: recommended