opentelemetry-instrumentation-servactory 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25e03df475b32f8de3c0c051a06a98b45ea31431ae23d7278fc68c4a2e1394b4
-  data.tar.gz: 56df92c6a1b50927730560fdb429a261e26be897107beec0e513a5ebe2c757f1
+  metadata.gz: 9541337e57c8059897f3a1f6cb0fb152beb791f2aff6c18a07c0074e57cecb80
+  data.tar.gz: ac2dc1dc511b67ef5bd353e9affa7ae7cd7169fb550a2da3f83310bd9d67d237
 SHA512:
-  metadata.gz: 1ba48f94bacee00877ce157069996c1d230bb105ccba488514f98174324706e03ccf7e1b751ab1855358f6e02a5bb36a39de1a042a7807f21c43f6324b07968b
-  data.tar.gz: 9315ee5f78f885fd77f3c937e605b286c3dc22d7f16eb6e58127439f13b49c00d956c3f3c163a160803baa9bf34d72100b8f64214ff2416f59ee171aa9a79812
+  metadata.gz: 1fe3f6ba462a056bd0d272a8df0d6571aaee3789ff40bd23ba594dd7bec6f8bc4490538f43c67ed3372e823c98ab6378fe82bfe92f5b9ba7998d65e5897cadc4
+  data.tar.gz: 3e02ec2270c2f4c3f334bc5e50fb2947db67e1c2edb4c5ed0ba3b1ac28ae0da2c7d1ca68a473f10d28483e24193b6a3cf96680ce5979e702ef5a726fd1be1a53

data/CONTRIBUTING.md

@@ -1,7 +1,65 @@
 # Contributing
 
-1. Fork it (https://github.com/servactory/opentelemetry-instrumentation-servactory/fork);
-2. Create your feature branch (`git checkout -b my-new-feature`);
-3. Commit your changes (`git commit -am "Add some feature"`);
-4. Push to the branch (`git push origin my-new-feature`);
-5. Create a new Pull Request.
+We welcome contributions to OpenTelemetry Instrumentation for Servactory! This guide will help you get started with contributing to the project.
+
+## Getting Started
+
+Before you begin, please make sure you have a [GitHub account](https://github.com/signup) and are familiar with Git workflows.
+
+## Contribution Workflow
+
+### 1. Fork the Repository
+
+Start by forking the [opentelemetry-instrumentation-servactory repository](https://github.com/servactory/opentelemetry-instrumentation-servactory/fork) to your GitHub account.
+
+### 2. Clone Your Fork
+
+```bash
+git clone https://github.com/YOUR_USERNAME/opentelemetry-instrumentation-servactory.git
+cd opentelemetry-instrumentation-servactory
+```
+
+### 3. Create a Feature Branch
+
+```bash
+git checkout -b my-new-feature
+```
+
+Use a descriptive branch name that reflects the changes you're making (e.g., `fix-validation-bug`, `add-logging-support`).
+
+### 4. Make Your Changes
+
+- Write clean, readable code that follows the project's coding standards
+- Add tests for new functionality
+- Update documentation as needed
+
+### 5. Commit Your Changes
+
+```bash
+git commit -am "Add some feature"
+```
+
+Write clear, concise commit messages that describe what changed and why.
+
+### 6. Push to Your Fork
+
+```bash
+git push origin my-new-feature
+```
+
+### 7. Create a Pull Request
+
+Visit the [original repository](https://github.com/servactory/opentelemetry-instrumentation-servactory) and create a new Pull Request from your feature branch.
+
+In your PR description:
+- Clearly describe the changes you've made
+- Reference any related issues
+- Explain the reasoning behind your approach
+
+## Questions?
+
+If you have questions about contributing, feel free to open an issue in the [main repository](https://github.com/servactory/opentelemetry-instrumentation-servactory/issues).
+
+---
+
+Thank you for contributing to OpenTelemetry Instrumentation for Servactory! 🎉

data/README.md

@@ -1,6 +1,6 @@
 # OpenTelemetry Servactory Instrumentation
 
-Todo: Add a description.
+Instrumentation for the [Servactory][servactory-home] service object framework. Automatically traces `call`/`call!` invocations and individual actions with span attributes, failure detection, and error recording.
 
 ## How do I get started?
 
@@ -10,7 +10,18 @@ Install the gem using:
 gem install opentelemetry-instrumentation-servactory
 ```
 
-Or, if you use [bundler][bundler-home], include `opentelemetry-instrumentation-servactory` in your `Gemfile`.
+Or, if you use [bundler][bundler-home], include `opentelemetry-instrumentation-servactory` in your `Gemfile`:
+
+```ruby
+gem "opentelemetry-instrumentation-servactory"
+```
+
+## Requirements
+
+| Requirement | Version |
+| --- | --- |
+| Servactory | `>= 2.16.0` |
+| Ruby | `>= 3.2` |
 
 ## Usage
 
@@ -18,11 +29,11 @@ To use the instrumentation, call `use` with the name of the instrumentation:
 
 ```ruby
 OpenTelemetry::SDK.configure do |c|
-  c.use 'OpenTelemetry::Instrumentation::Servactory'
+  c.use("OpenTelemetry::Instrumentation::Servactory")
 end
 ```
 
-Alternatively, you can also call `use_all` to install all the available instrumentation.
+Alternatively, you can also call `use_all` to install all the available instrumentation:
 
 ```ruby
 OpenTelemetry::SDK.configure do |c|
@@ -30,13 +41,64 @@ OpenTelemetry::SDK.configure do |c|
 end
 ```
 
-## Examples
+## Configuration Options
+
+| Option | Default | Type | Description |
+| --- | --- | --- | --- |
+| `trace_actions` | `true` | Boolean | Create child spans for each `make` action |
+| `record_input_names` | `true` | Boolean | Record input names as a span attribute |
+| `record_output_names` | `true` | Boolean | Record output names as a span attribute |
+
+Example with custom configuration:
+
+```ruby
+OpenTelemetry::SDK.configure do |c|
+  c.use(
+    "OpenTelemetry::Instrumentation::Servactory", 
+    {
+      trace_actions: true,
+      record_input_names: false,
+      record_output_names: false
+    }
+  )
+end
+```
+
+## Span Structure
+
+Each `call`/`call!` invocation creates a root span. When `trace_actions` is enabled, each `make` action creates a child span.
+
+```
+Users::CreateService call              (root span)
+  |-- Users::CreateService validate    (child span per action)
+  |-- Users::CreateService create_user
+  |-- Users::CreateService send_email
+```
+
+### Span Attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `code.namespace` | String | Service class name |
+| `code.function` | String | Method name (`call`, `call!`, or action name) |
+| `servactory.version` | String | Servactory library version |
+| `servactory.result` | String | `success`, `failure`, or `error` |
+| `servactory.input_names` | Array | Input attribute names (when `record_input_names` is enabled) |
+| `servactory.output_names` | Array | Output attribute names (when `record_output_names` is enabled) |
+
+### Failure Events
+
+When a service fails via `fail!`, a `servactory.failure` event is added to the span with:
 
-Example usage can be seen in the [`./example/trace_demonstration.rb` file](https://github.com/servactory/opentelemetry-instrumentation-servactory/blob/main/example/trace_demonstration.rb)
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `servactory.failure.type` | String | Failure type (if provided) |
+| `servactory.failure.message` | String | Failure message |
 
 ## License
 
 The `opentelemetry-instrumentation-servactory` gem is distributed under the MIT license. See [LICENSE][license-github] for more information.
 
+[servactory-home]: https://servactory.com
 [bundler-home]: https://bundler.io
 [license-github]: https://github.com/servactory/opentelemetry-instrumentation-servactory/blob/main/LICENSE

data/lib/opentelemetry/instrumentation/servactory/instrumentation.rb

@@ -4,20 +4,42 @@ module OpenTelemetry
   module Instrumentation
     module Servactory
       class Instrumentation < OpenTelemetry::Instrumentation::Base
+        instrumentation_version VERSION::STRING
+
+        MINIMUM_VERSION = Gem::Version.new("2.16.0")
+
         install do |_config|
           require_dependencies
+          patch_callable
+          patch_runner if config[:trace_actions]
         end
 
         present do
-          # TODO: Replace true with a definition check of the gem being instrumented
-          # Example: `defined?(::Rack)`
-          true
+          defined?(::Servactory)
         end
 
+        compatible do
+          gem_version = Gem::Version.new(::Servactory::VERSION::STRING)
+          gem_version >= MINIMUM_VERSION
+        end
+
+        option :trace_actions, default: true, validate: :boolean
+        option :record_input_names, default: true, validate: :boolean
+        option :record_output_names, default: true, validate: :boolean
+
         private
 
         def require_dependencies
-          # TODO: Include instrumentation dependencies
+          require_relative "patches/callable"
+          require_relative "patches/runner"
+        end
+
+        def patch_callable
+          ::Servactory::Context::Callable.prepend(Patches::Callable)
+        end
+
+        def patch_runner
+          ::Servactory::Actions::Tools::Runner.prepend(Patches::Runner)
         end
       end
     end

data/lib/opentelemetry/instrumentation/servactory/patches/callable.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module OpenTelemetry
+  module Instrumentation
+    module Servactory
+      module Patches
+        module Callable # rubocop:disable Metrics/ModuleLength
+          def call(...) # rubocop:disable Metrics/MethodLength
+            service_name = name || "AnonymousService"
+            attributes = _otel_build_span_attributes(service_name, "call")
+
+            span = _otel_tracer.start_span("#{service_name} call", attributes:, kind: :internal)
+            OpenTelemetry::Trace.with_span(span) do
+              result = super
+              _otel_record_result(span, result)
+              result
+            rescue StandardError => e
+              _otel_record_exception_on_span(span, e)
+              raise
+            ensure
+              span.finish
+            end
+          end
+
+          def call!(...) # rubocop:disable Metrics/MethodLength
+            service_name = name || "AnonymousService"
+            attributes = _otel_build_span_attributes(service_name, "call!")
+
+            span = _otel_tracer.start_span("#{service_name} call!", attributes:, kind: :internal)
+            OpenTelemetry::Trace.with_span(span) do
+              result = super
+              _otel_mark_span_success(span)
+              result
+            rescue StandardError => e
+              _otel_record_exception_on_span(span, e)
+              raise
+            ensure
+              span.finish
+            end
+          end
+
+          private
+
+          def _otel_build_span_attributes(service_name, method_name)
+            attributes = {
+              "code.namespace" => service_name,
+              "code.function" => method_name,
+              "servactory.version" => ::Servactory::VERSION::STRING
+            }
+            _otel_append_attribute_names(attributes)
+            attributes
+          end
+
+          def _otel_append_attribute_names(attributes)
+            config = OpenTelemetry::Instrumentation::Servactory::Instrumentation.instance.config
+
+            if config[:record_input_names]
+              names = _otel_input_names
+              attributes["servactory.input_names"] = names unless names.empty?
+            end
+
+            return unless config[:record_output_names]
+
+            names = _otel_output_names
+            attributes["servactory.output_names"] = names unless names.empty?
+          end
+
+          def _otel_input_names
+            send(:collection_of_inputs).names.map(&:to_s)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(exception: e, message: "Failed to collect Servactory input names")
+            []
+          end
+
+          def _otel_output_names
+            send(:collection_of_outputs).names.map(&:to_s)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(exception: e, message: "Failed to collect Servactory output names")
+            []
+          end
+
+          def _otel_record_result(span, result)
+            if result.respond_to?(:failure?) && result.failure?
+              _otel_record_failure_on_span(span, result)
+              span.set_attribute("servactory.result", "failure")
+            else
+              _otel_mark_span_success(span)
+            end
+          end
+
+          def _otel_mark_span_success(span)
+            span.set_attribute("servactory.result", "success")
+            span.status = OpenTelemetry::Trace::Status.ok
+          end
+
+          def _otel_record_failure_on_span(span, result)
+            error = result.respond_to?(:error) ? result.error : nil
+            message = _otel_error_message_for(error)
+
+            span.add_event("servactory.failure", attributes: _otel_failure_attributes(error))
+            span.status = OpenTelemetry::Trace::Status.error(message)
+          end
+
+          def _otel_record_exception_on_span(span, exception)
+            span.record_exception(exception)
+
+            if exception.respond_to?(:type)
+              span.set_attribute("servactory.result", "failure")
+              span.status = OpenTelemetry::Trace::Status.error(_otel_error_message_for(exception))
+            else
+              span.set_attribute("servactory.result", "error")
+              span.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{exception.class}")
+            end
+          end
+
+          def _otel_error_message_for(error)
+            return "Service failure" unless error
+
+            if error.respond_to?(:message)
+              error.message.to_s
+            else
+              error.to_s
+            end
+          end
+
+          def _otel_failure_attributes(error)
+            attrs = {}
+            attrs["servactory.failure.type"] = error.type.to_s if error.respond_to?(:type) && error.type
+            attrs["servactory.failure.message"] = error.message.to_s if error.respond_to?(:message) && error.message
+            attrs
+          end
+
+          def _otel_tracer
+            OpenTelemetry::Instrumentation::Servactory::Instrumentation.instance.tracer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/servactory/patches/runner.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OpenTelemetry
+  module Instrumentation
+    module Servactory
+      module Patches
+        module Runner
+          private
+
+          def call_action(action)
+            span = _otel_start_action_span(action)
+            OpenTelemetry::Trace.with_span(span) do
+              super
+            rescue StandardError => e
+              span.record_exception(e)
+              span.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{e.class}")
+              raise
+            ensure
+              span.finish
+            end
+          end
+
+          def _otel_start_action_span(action)
+            service_name = @context&.class&.name || "AnonymousService"
+            attributes = _otel_build_action_attributes(service_name, action.name.to_s)
+
+            _otel_tracer.start_span("#{service_name} #{action.name}", attributes:, kind: :internal)
+          end
+
+          def _otel_build_action_attributes(service_name, action_name)
+            {
+              "code.namespace" => service_name,
+              "code.function" => action_name,
+              "servactory.version" => ::Servactory::VERSION::STRING
+            }
+          end
+
+          def _otel_tracer
+            OpenTelemetry::Instrumentation::Servactory::Instrumentation.instance.tracer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/servactory/version.rb

@@ -5,7 +5,7 @@ module OpenTelemetry
     module Servactory
       module VERSION
         MAJOR = 0
-        MINOR = 1
+        MINOR = 2
         PATCH = 0
         PRE = nil
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-instrumentation-servactory
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.0
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.0
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-instrumentation-base
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.23.0
+        version: '0.22'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.23.0
+        version: '0.22'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: servactory
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.16.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.16.0
 - !ruby/object:Gem::Dependency
   name: servactory-rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +121,8 @@ files:
 - lib/opentelemetry/instrumentation.rb
 - lib/opentelemetry/instrumentation/servactory.rb
 - lib/opentelemetry/instrumentation/servactory/instrumentation.rb
+- lib/opentelemetry/instrumentation/servactory/patches/callable.rb
+- lib/opentelemetry/instrumentation/servactory/patches/runner.rb
 - lib/opentelemetry/instrumentation/servactory/version.rb
 - lib/opentelemetry_instrumentation_servactory.rb
 homepage: https://github.com/servactory/opentelemetry-instrumentation-servactory
@@ -119,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Servactory instrumentation for the OpenTelemetry framework
 test_files: []