cinc-otel 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ce4eaaf69cd3aac06552a6caee779015421915aa96bf2485295898d7488e0354
+  data.tar.gz: 968d002ac34cc401777b1b2ef073530675720c21cedf0a4fef6d4121f4833f50
+SHA512:
+  metadata.gz: 7616575341ee0cb0a51aef37e2c65212a7cf6c8b4eecf600c87594308ca68d16941273aae9dab3a05daf9b312daa9b8026fbb9aab97a476ae7d25504be1ff0d3
+  data.tar.gz: ce767e8287d05498f9264ba39a4993d0845c3c802ea9723309b69289b3bb720ed495e0b357e093e6922b69de644ac95f3b09a306e897cb7e1f02d4061d3fc9e3

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0]
+
+### Added
+
+- `CincOtel::Handler`, a `Chef::EventDispatch` subscriber that emits an
+  OpenTelemetry span tree for each Cinc Client run: a `chef.run` root span, a
+  span per run phase, and a span per resource action.
+- `__tenant` resource attribute tagging via `OTEL_RESOURCE_ATTRIBUTES` or the
+  `register!(tenant:)` keyword.
+- Loads the OTLP exporter at require time so the default
+  `OTEL_TRACES_EXPORTER=otlp` configuration exports spans without extra setup.
+- Nests the run under a parent trace supplied via the W3C `TRACEPARENT` /
+  `TRACESTATE` environment variables, so a run joins an OpenTelemetry-aware
+  caller's trace.
+
+[Unreleased]: https://github.com/fastly/cinc-otel/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/fastly/cinc-otel/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 Jason Cook
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,176 @@
+# cinc-otel
+
+OpenTelemetry run tracing for [Cinc Client](https://cinc.sh/).
+
+`cinc-otel` emits an OpenTelemetry trace for each Cinc Client run: a `chef.run`
+root span, a child span for each run phase (node load, cookbook sync,
+compilation, converge, ...), and one span per resource action. The trace makes
+it easy to see where run time is spent and to correlate failed or slow runs
+with the rest of your distributed tracing in a backend such as Tempo or Jaeger.
+
+It is implemented as a `Chef::EventDispatch` handler. The event stream is the
+only interface that delivers live, paired start/complete events for every phase
+and resource action, which map one-to-one onto span open/close with real
+wall-clock timestamps.
+
+## Requirements
+
+`cinc-otel` is loaded **inside a cinc-client process** and relies on Chef's
+`Chef::EventDispatch::Base`, `Chef::Log`, and `Chef::Config` already being
+loaded. It does not depend on the `chef` gem itself and does not pull it in;
+Chef is expected to be present in the runtime that loads this gem. The gem is
+tested against Cinc Client 18 and 19.
+
+The OpenTelemetry SDK and OTLP exporter (`opentelemetry-sdk`,
+`opentelemetry-exporter-otlp`) are runtime dependencies and are required when
+the handler loads, so they are always available.
+
+## Installation
+
+Add it to the gems available to cinc-client. For example, in a Cinc
+installation that uses `cinc gem install`:
+
+```shell
+cinc gem install cinc-otel
+```
+
+Or add it to your bundle:
+
+```ruby
+gem "cinc-otel"
+```
+
+## Enabling tracing
+
+Add the following to `client.rb` (or `solo.rb`):
+
+```ruby
+require "cinc-otel"
+CincOtel::Handler.register!
+```
+
+`register!` is idempotent: applications such as chef-solo evaluate the config
+file more than once, and only one handler is ever registered.
+
+The exporter and endpoint are configured through the standard `OTEL_*`
+environment variables, for example:
+
+```shell
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+
+If span emission ever raises mid-run, the handler disables itself for the rest
+of the run rather than letting the error propagate — tracing can never break a
+converge.
+
+If something else in the process has already configured the global
+OpenTelemetry SDK before the handler loads, that configuration (including its
+resource attributes) is used as-is.
+
+## Service name and tenant
+
+The service name defaults to `chef-client` and can be overridden with
+`OTEL_SERVICE_NAME`.
+
+Spans can be tagged with a `__tenant` resource attribute (used by Tempo
+multi-tenancy for search and tail-sampling routing) either through the standard
+env var:
+
+```shell
+OTEL_RESOURCE_ATTRIBUTES=__tenant=controlplane
+```
+
+or explicitly at registration, which takes precedence over the env var:
+
+```ruby
+CincOtel::Handler.register!(tenant: "controlplane")
+```
+
+## Connecting to a parent trace
+
+When cinc-client is invoked by an OpenTelemetry-aware caller (a CI runner,
+`otel-cli`, an orchestrator), export the standard W3C Trace Context
+environment variables before the run and the `chef.run` span — and the whole
+run tree beneath it — will nest under the caller's span instead of starting a
+new trace:
+
+```shell
+export TRACEPARENT=00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+export TRACESTATE=vendor=value   # optional
+cinc-client
+```
+
+`TRACEPARENT`/`TRACESTATE` are the W3C Trace Context format emitted by tools
+such as `otel-cli`, GitHub Actions, and Buildkite. If `TRACEPARENT` is absent
+or malformed, the run starts its own root trace as usual.
+
+## Span structure
+
+```text
+chef.run                          chef.version, chef.run_id, chef.node.name, chef.environment
+├─ chef.registration
+├─ chef.node_load
+├─ chef.cookbook_resolution
+├─ chef.cookbook_clean
+├─ chef.cookbook_sync
+├─ chef.cookbook_gems
+├─ chef.cookbook_compilation
+│  ├─ chef.library_load
+│  ├─ chef.ohai_plugin_load
+│  ├─ chef.compliance_load
+│  ├─ chef.attribute_load
+│  ├─ chef.lwrp_load
+│  ├─ chef.definition_load
+│  └─ chef.recipe_load
+├─ chef.converge
+│  └─ one span per resource action, named e.g. file[/etc/motd]
+└─ chef.handlers
+```
+
+Each resource span carries `chef.resource.type`, `chef.resource.name`,
+`chef.resource.action`, `chef.resource.cookbook` and `chef.resource.recipe`,
+plus outcome detail:
+
+* `chef.resource.updated` — `true`/`false` for converged resources
+* `chef.resource.skipped` and `chef.resource.skip_reason` — for resources
+  skipped by a guard or `action :nothing`
+* `chef.resource.notification_type` and `chef.resource.notifying_resource` —
+  when the action ran due to a notification
+* failed resources record the exception on the span and set error status;
+  retries appear as `retry` span events
+
+## Testing locally
+
+The SDK's console exporter prints spans to stdout, which is handy for verifying
+output without a collector:
+
+```shell
+OTEL_TRACES_EXPORTER=console cinc-solo -c solo.rb -o 'recipe[my_cookbook]'
+```
+
+## Development
+
+```shell
+bundle install
+bundle exec rake        # runs chefstyle + rspec
+bundle exec rspec       # tests only
+bundle exec rake style  # lint only
+```
+
+The unit suite runs without a Chef installation beyond the `chef` dev gem. There
+is also an end-to-end integration test that runs a real `chef-solo`/`cinc-solo`
+converge and asserts the emitted OpenTelemetry spans over the OTLP exporter. It
+is excluded from the default run and is skipped unless a solo binary is present:
+
+```shell
+CINC_OTEL_INTEGRATION=1 bundle exec rspec --tag integration spec/integration
+# or
+bundle exec rake integration
+```
+
+CI runs it in a dedicated job that installs Cinc Client and installs the built
+gem into its embedded Ruby.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

data/lib/cinc-otel.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cinc_otel"

data/lib/cinc_otel/handler.rb

@@ -0,0 +1,281 @@
+#
+# Author:: Jason Cook (<jasonc@simpleideas.org>)
+# Copyright:: Copyright (c) Jason Cook
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "opentelemetry/sdk"
+# Loaded so the standard OTEL_TRACES_EXPORTER=otlp configuration works out of
+# the box: the SDK only wires up an exporter whose constant is already loaded,
+# it does not require the exporter gem itself.
+require "opentelemetry-exporter-otlp"
+
+require "chef/event_dispatch/base"
+require "chef/log"
+require "chef/config"
+require "chef/version"
+
+require_relative "version"
+
+module CincOtel
+  # Emits an OpenTelemetry trace for the Cinc Client run: a root span for
+  # the run, child spans for each phase (node load, cookbook sync,
+  # compilation, converge, ...) and one span per resource action.
+  #
+  # Enable it from client.rb (or solo.rb):
+  #
+  #   require "cinc-otel"
+  #   CincOtel::Handler.register!
+  #
+  # Exporter and endpoint are configured through the standard OTEL_*
+  # environment variables. The opentelemetry-sdk gem (and
+  # opentelemetry-exporter-otlp for the default OTLP exporter) are runtime
+  # dependencies, so they are always available.
+  #
+  # Spans can be tagged with a __tenant resource attribute (used by Tempo
+  # multi-tenancy for search and tail-sampling routing) either through the
+  # standard env var:
+  #
+  #   OTEL_RESOURCE_ATTRIBUTES=__tenant=controlplane
+  #
+  # or explicitly, which takes precedence over the env var:
+  #
+  #   CincOtel::Handler.register!(tenant: "controlplane")
+  class Handler < Chef::EventDispatch::Base
+    # Adds the handler to Chef::Config[:event_handlers]. Idempotent, because
+    # some applications (chef-solo) evaluate the config file more than once
+    # and a second handler would emit every span twice.
+    def self.register!(**opts)
+      return if Chef::Config[:event_handlers].any? { |handler| handler.is_a?(self) }
+
+      Chef::Config[:event_handlers] << new(**opts)
+    end
+
+    def initialize(tracer_provider: nil, tenant: nil)
+      @stack = []
+      @tracer_provider = tracer_provider || default_tracer_provider(tenant)
+      @tracer = @tracer_provider&.tracer("cinc-otel", CincOtel::VERSION)
+    end
+
+    def run_start(version, run_status)
+      start_span("chef.run", {
+        "chef.version" => version.to_s,
+        "chef.run_id" => run_status.run_id.to_s,
+      }, with_parent: remote_parent_context)
+    end
+
+    def run_completed(node, run_status)
+      end_span("chef.run", ok: true)
+      @tracer_provider&.force_flush
+    end
+
+    def run_failed(exception, run_status)
+      end_span("chef.run", error: exception)
+      @tracer_provider&.force_flush
+    end
+
+    def node_load_success(node)
+      root_span&.set_attribute("chef.node.name", node.name.to_s)
+      root_span&.set_attribute("chef.environment", node.chef_environment.to_s)
+    end
+
+    def ohai_completed(node)
+      current_span&.add_event("ohai_completed")
+    end
+
+    def deprecation(message, location = nil)
+      text = message.respond_to?(:message) ? message.message.to_s : message.to_s
+      attributes = { "chef.deprecation.message" => text }
+      attributes["chef.deprecation.location"] = location.to_s if location
+      current_span&.add_event("deprecation", attributes:)
+    end
+
+    # Paired phase events: the start event opens a span, the end event
+    # closes it. Event arguments are not recorded on phase spans.
+    {
+      "chef.registration" => %i{registration_start registration_completed},
+      "chef.node_load" => %i{node_load_start node_load_completed},
+      "chef.cookbook_resolution" => %i{cookbook_resolution_start cookbook_resolution_complete},
+      "chef.cookbook_clean" => %i{cookbook_clean_start cookbook_clean_complete},
+      "chef.cookbook_sync" => %i{cookbook_sync_start cookbook_sync_complete},
+      "chef.cookbook_gems" => %i{cookbook_gem_start cookbook_gem_finished},
+      "chef.cookbook_compilation" => %i{cookbook_compilation_start cookbook_compilation_complete},
+      "chef.library_load" => %i{library_load_start library_load_complete},
+      "chef.lwrp_load" => %i{lwrp_load_start lwrp_load_complete},
+      "chef.ohai_plugin_load" => %i{ohai_plugin_load_start ohai_plugin_load_complete},
+      "chef.attribute_load" => %i{attribute_load_start attribute_load_complete},
+      "chef.definition_load" => %i{definition_load_start definition_load_complete},
+      "chef.recipe_load" => %i{recipe_load_start recipe_load_complete},
+      "chef.compliance_load" => %i{compliance_load_start compliance_load_complete},
+      "chef.converge" => %i{converge_start converge_complete},
+      "chef.handlers" => %i{handlers_start handlers_completed},
+    }.each do |span_name, (start_event, end_event)|
+      define_method(start_event) { |*_args| start_span(span_name) }
+      define_method(end_event) { |*_args| end_span(span_name) }
+    end
+
+    # Failure events close their phase span with error status; the value is
+    # the position of the exception in the event's arguments.
+    {
+      registration_failed: ["chef.registration", 1],
+      node_load_failed: ["chef.node_load", 1],
+      run_list_expand_failed: ["chef.node_load", 1],
+      cookbook_resolution_failed: ["chef.cookbook_resolution", 1],
+      cookbook_sync_failed: ["chef.cookbook_sync", 1],
+      cookbook_gem_failed: ["chef.cookbook_gems", 0],
+      converge_failed: ["chef.converge", 0],
+    }.each do |event, (span_name, exception_index)|
+      define_method(event) { |*args| end_span(span_name, error: args[exception_index]) }
+    end
+
+    def resource_action_start(resource, action, notification_type = nil, notifier = nil)
+      attributes = {
+        "chef.resource.type" => resource.resource_name.to_s,
+        "chef.resource.name" => resource.name.to_s,
+        "chef.resource.action" => action.to_s,
+      }
+      attributes["chef.resource.cookbook"] = resource.cookbook_name.to_s if resource.cookbook_name
+      attributes["chef.resource.recipe"] = resource.recipe_name.to_s if resource.recipe_name
+      attributes["chef.resource.notification_type"] = notification_type.to_s if notification_type
+      attributes["chef.resource.notifying_resource"] = notifier.to_s if notifier
+      start_span(resource.to_s, attributes)
+    end
+
+    def resource_updated(resource, action)
+      current_span&.set_attribute("chef.resource.updated", true)
+    end
+
+    def resource_up_to_date(resource, action)
+      current_span&.set_attribute("chef.resource.updated", false)
+    end
+
+    def resource_skipped(resource, action, conditional)
+      span = current_span
+      return unless span
+
+      span.set_attribute("chef.resource.skipped", true)
+      span.set_attribute("chef.resource.skip_reason", conditional.to_text)
+    end
+
+    def resource_failed(resource, action, exception)
+      span = current_span
+      return unless span
+
+      span.record_exception(exception)
+      span.status = OpenTelemetry::Trace::Status.error(exception.message)
+    end
+
+    def resource_failed_retriable(resource, action, retry_count, exception)
+      current_span&.add_event("retry", attributes: {
+        "chef.resource.retries_remaining" => retry_count,
+        "exception.message" => exception.message,
+      })
+    end
+
+    def resource_completed(resource)
+      end_span(resource.to_s)
+    end
+
+    private
+
+    def current_span
+      @stack.last && @stack.last[1]
+    end
+
+    def root_span
+      @stack.first && @stack.first[1]
+    end
+
+    # Opens a span as a child of whatever span is currently innermost and
+    # pushes it on the stack. Events arrive synchronously on one thread, so
+    # the stack mirrors the nesting of the run.
+    def start_span(name, attributes = {}, with_parent: nil)
+      return unless @tracer
+
+      parent = @stack.last
+      context = if parent
+                  OpenTelemetry::Trace.context_with_span(parent[1])
+                else
+                  with_parent || OpenTelemetry::Context.current
+                end
+      @stack << [name, @tracer.start_span(name, with_parent: context, attributes:)]
+    end
+
+    # Finishes the named span. If intervening spans were left open (an end
+    # event that never fired), they are finished too; if the named span is
+    # not open at all, this is a no-op.
+    def end_span(name, error: nil, ok: false)
+      return unless @stack.any? { |n, _| n == name }
+
+      loop do
+        span_name, span = @stack.pop
+        if span_name == name
+          if error
+            span.record_exception(error)
+            span.status = OpenTelemetry::Trace::Status.error(error.message)
+          elsif ok
+            span.status = OpenTelemetry::Trace::Status.ok
+          end
+        end
+        span.finish
+        break if span_name == name
+      end
+    end
+
+    # Extracts a remote trace context from the standard W3C TRACEPARENT (and
+    # optional TRACESTATE) environment variables so the run can nest under an
+    # OpenTelemetry-aware caller's trace. Absent or malformed headers yield the
+    # current (empty) context, so chef.run simply starts a new root trace.
+    def remote_parent_context
+      carrier = {}
+      carrier["traceparent"] = ENV["TRACEPARENT"] if ENV["TRACEPARENT"]
+      carrier["tracestate"] = ENV["TRACESTATE"] if ENV["TRACESTATE"]
+      OpenTelemetry.propagation.extract(carrier)
+    end
+
+    def default_tracer_provider(tenant = nil)
+      unless OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+        OpenTelemetry::SDK.configure do |config|
+          config.service_name = ENV["OTEL_SERVICE_NAME"] || "chef-client"
+          # Configurator#resource= merges into the default resource, which
+          # already carries OTEL_RESOURCE_ATTRIBUTES, so an explicit tenant
+          # wins over the env var.
+          config.resource = OpenTelemetry::SDK::Resources::Resource.create("__tenant" => tenant.to_s) if tenant
+        end
+      end
+      OpenTelemetry.tracer_provider
+    end
+
+    # Tracing must never break the chef run: if any event method raises,
+    # log it and ignore all further events instead of letting the error
+    # propagate into the event dispatcher. Defined last so it wraps every
+    # event method above.
+    crash_guard = Module.new do
+      Handler.public_instance_methods(false).each do |event|
+        define_method(event) do |*args|
+          return if @broken
+
+          begin
+            super(*args)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            @broken = true
+            Chef::Log.warn("OTel tracing handler failed (#{e.class}: #{e.message}); tracing disabled for the rest of this run")
+          end
+        end
+      end
+    end
+    prepend crash_guard
+  end
+end

data/lib/cinc_otel/version.rb

@@ -0,0 +1,21 @@
+#
+# Author:: Jason Cook (<jasonc@simpleideas.org>)
+# Copyright:: Copyright (c) Jason Cook
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module CincOtel
+  VERSION = "1.0.0".freeze
+end

data/lib/cinc_otel.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "cinc_otel/version"
+require_relative "cinc_otel/handler"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: cinc-otel
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jason Cook
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.29'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.29'
+description: |
+  Emits an OpenTelemetry span tree for each Cinc Client run: a chef.run root
+  span, a child span for each run phase, and one span per resource action.
+  Implemented as a Chef::EventDispatch handler. Loaded inside a cinc-client
+  process; OpenTelemetry exporter and endpoint are configured through the
+  standard OTEL_* environment variables.
+email:
+- jasonc@simpleideas.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/cinc-otel.rb
+- lib/cinc_otel.rb
+- lib/cinc_otel/handler.rb
+- lib/cinc_otel/version.rb
+homepage: https://github.com/fastly/cinc-otel
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/fastly/cinc-otel
+  source_code_uri: https://github.com/fastly/cinc-otel
+  changelog_uri: https://github.com/fastly/cinc-otel/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: OpenTelemetry run tracing for Cinc Client
+test_files: []