Merge branch 'markdownlint-link' of github.com:xuan-cao-swi/opentelem…

…etry-ruby into markdownlint-link

.codespellignore

@@ -0,0 +1,2 @@
+ot
+te

.codespellrc

@@ -0,0 +1,10 @@
+# https://github.com/codespell-project/codespell
+[codespell]
+builtin = clear,rare,informal
+check-filenames =
+check-hidden =
+ignore-words = .codespellignore
+interactive = 1
+skip = .git,venv,coverage,doc,docs
+uri-ignore-words-list = *
+write =

.github/workflows/ci.yml

@@ -208,3 +208,9 @@ jobs:
         with:
           gem: "${{ matrix.gem }}"
           ruby: "truffleruby"
+
+  codespell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: make codespell

.gitignore

@@ -22,4 +22,7 @@
 # rbenv configuration
 .ruby-version
 
+# Python virtual env for codespell
+venv
+
 tags

CHANGELOG.md

@@ -46,6 +46,6 @@ All notable changes to this project were documented in this file. This is of his
 
 * [#286](https://github.com/open-telemetry/opentelemetry-ruby/pull/286) Update Schedule. ([@fbogsany](https://github.com/fbogsany))
 
-* [#288](https://github.com/open-telemetry/opentelemetry-ruby/pull/288) Fix api/sdk gem install instuctions. ([@mwlang](https://github.com/mwlang))
+* [#288](https://github.com/open-telemetry/opentelemetry-ruby/pull/288) Fix api/sdk gem install instructions. ([@mwlang](https://github.com/mwlang))
 
 * [#294](https://github.com/open-telemetry/opentelemetry-ruby/pull/294) Add CHANGELOG. ([@ericmustin](https://github.com/ericmustin))

Makefile

@@ -0,0 +1,35 @@
+# Virtualized python tools via docker
+
+# The directory where the virtual environment is created.
+VENVDIR := venv
+
+PYTOOLS := $(VENVDIR)/bin
+
+# The pip executable in the virtual environment.
+PIP := $(PYTOOLS)/pip
+
+# The directory in the docker image where the current directory is mounted.
+WORKDIR := /workdir
+
+# The python image to use for the virtual environment.
+PYTHONIMAGE := python:3.11.3-slim-bullseye
+
+# Run the python image with the current directory mounted.
+DOCKERPY := docker run --rm -v "$(CURDIR):$(WORKDIR)" -w $(WORKDIR) $(PYTHONIMAGE)
+
+# Create a virtual environment for Python tools.
+$(PYTOOLS):
+# The `--upgrade` flag is needed to ensure that the virtual environment is
+# created with the latest pip version.
+	@$(DOCKERPY) bash -c "python3 -m venv $(VENVDIR) && $(PIP) install --upgrade pip"
+
+# Install python packages into the virtual environment.
+$(PYTOOLS)/%: $(PYTOOLS)
+	@$(DOCKERPY) $(PIP) install -r requirements.txt
+
+CODESPELL = $(PYTOOLS)/codespell
+$(CODESPELL): PACKAGE=codespell
+
+.PHONY: codespell
+codespell: $(CODESPELL)
+	@$(DOCKERPY) $(CODESPELL)

api/CHANGELOG.md

@@ -71,7 +71,7 @@
 
 * BREAKING CHANGE: Remove optional parent_context from in_span [729](https://github.com/open-telemetry/opentelemetry-ruby/pull/729)
 * BREAKING CHANGE: Refactor Baggage to remove Noop* [800](https://github.com/open-telemetry/opentelemetry-ruby/pull/800)
-  - The noop baggage manger has been removed.
+  - The noop baggage manager has been removed.
   - The baggage management methods are now available through OpenTelemetry::Baggage#method, previously OpenTelemetry.baggage#method
 * BREAKING CHANGE: Total order constraint on span.status= [805](https://github.com/open-telemetry/opentelemetry-ruby/pull/805)
   - The OpenTelemetry::Trace::Util::HttpToStatus module has been removed as it was incorrectly setting the span status to OK for codes codes in the range 100..399

api/README.md

@@ -12,7 +12,10 @@ OpenTelemetry provides a single set of APIs, libraries, agents, and collector se
 
 The `opentelemetry-api` gem defines the core OpenTelemetry interfaces in the form of abstract classes and no-op implementations. That is, it defines interfaces and data types sufficient for a library or application to code against to produce telemetry data, but does not actually collect, analyze, or export the data.
 
-To collect and analyze telemetry data, *applications* should also install a concrete implementation of the API, such as the `opentelemetry-sdk` gem. However, *libraries* that produce telemetry data should depend only on `opentelemetry-api`, deferring the choise of concrete implementation to the application developer.
+To collect and analyze telemetry data, *applications* should also
+install a concrete implementation of the API, such as the
+`opentelemetry-sdk` gem. However, *libraries* that produce telemetry
+data should depend only on `opentelemetry-api`, deferring the choice of concrete implementation to the application developer.
 
 ## How do I get started?
 

api/lib/opentelemetry.rb

@@ -34,7 +34,7 @@ def logger
   # @return [Callable] configured error handler or a default that logs the
   #   exception and message at ERROR level.
   def error_handler
-    @error_handler ||= ->(exception: nil, message: nil) { logger.error("OpenTelemetry error: #{[message, exception&.message].compact.join(' - ')}") }
+    @error_handler ||= ->(exception: nil, message: nil) { logger.error("OpenTelemetry error: #{[message, exception&.message, exception&.backtrace&.first].compact.join(' - ')}") }
   end
 
   # Handles an error by calling the configured error_handler.

api/lib/opentelemetry/baggage.rb

@@ -73,7 +73,7 @@ def raw_entries(context: Context.current)
     # @param [String] key The key to store this value under
     # @param [String] value String value to be stored under key
     # @param [optional String] metadata This is here to store properties
-    #   received from other W3C Baggage impelmentations but is not exposed in
+    #   received from other W3C Baggage implementations but is not exposed in
     #   OpenTelemetry. This is condsidered private API and not for use by
     #   end-users.
     # @param [optional Context] context The context to update with new

api/lib/opentelemetry/baggage/builder.rb

@@ -21,7 +21,7 @@ def initialize(entries)
       # @param [String] key The key to store this value under
       # @param [String] value String value to be stored under key
       # @param [optional String] metadata This is here to store properties
-      #   received from other W3C Baggage impelmentations but is not exposed in
+      #   received from other W3C Baggage implementations but is not exposed in
       #   OpenTelemetry. This is condsidered private API and not for use by
       #   end-users.
       def set_value(key, value, metadata: nil)

api/lib/opentelemetry/baggage/propagation/text_map_propagator.rb

@@ -100,7 +100,7 @@ def encode(baggage)
 
         def encode_value(key, entry)
           result = +"#{CGI.escape(key.to_s)}=#{CGI.escape(entry.value.to_s)}"
-          # We preserve metadata recieved on extract and assume it's already formatted
+          # We preserve metadata received on extract and assume it's already formatted
           # for transport. It's sent as-is without further processing.
           result << ";#{entry.metadata}" if entry.metadata
           result

api/lib/opentelemetry/trace/propagation/trace_context.rb

@@ -10,7 +10,7 @@
 module OpenTelemetry
   module Trace
     module Propagation
-      # The TraceContext module contains injectors, extractors, and utilties
+      # The TraceContext module contains injectors, extractors, and utilities
       # for context propagation in the W3C Trace Context format.
       module TraceContext
         extend self

api/lib/opentelemetry/trace/span_kind.rb

@@ -26,7 +26,7 @@ module SpanKind
       # spans.
       PRODUCER = :producer
 
-      # Indicates that the span describes consumer recieving a message from a broker. Unlike client
+      # Indicates that the span describes consumer receiving a message from a broker. Unlike client
       # and server, there is no direct critical path latency relationship between producer and
       # consumer spans.
       CONSUMER = :consumer

api/test/opentelemetry/context/propagation/text_map_getter_test.rb

@@ -20,7 +20,7 @@
       _(getter.get(carrier, 'x-source-id')).must_equal('123')
     end
 
-    it 'returns nil for non-existant key' do
+    it 'returns nil for non-existent key' do
       _(getter.get(carrier, 'not-here')).must_be_nil
     end
   end

api/test/opentelemetry/trace/propagation/trace_context/trace_parent_test.rb

@@ -76,7 +76,7 @@
       _(tp.to_s).must_equal(expected)
     end
 
-    it 'must ignore flags it doesnt know (use the mask)' do
+    it 'must ignore flags it doesn\'t know (use the mask)' do
       value = '00-0000000000000000000000000000000a-000000000000000a-ff'
       assert TraceParent.from_string(value).sampled?
       value = '00-0000000000000000000000000000000a-000000000000000a-04'

api/test/opentelemetry_test.rb

@@ -96,7 +96,9 @@ def error(message)
       rescue StandardError => e
         OpenTelemetry.handle_error(exception: e, message: 'hi')
       end
-      _(OpenTelemetry.logger.messages).must_equal ['OpenTelemetry error: foo', 'OpenTelemetry error: hell', 'OpenTelemetry error: hi - bar']
+      _(OpenTelemetry.logger.messages[0]).must_equal('OpenTelemetry error: foo')
+      _(OpenTelemetry.logger.messages[1]).must_match(%r{OpenTelemetry error: hell - .+/opentelemetry_test\.rb:\d+:in .+'})
+      _(OpenTelemetry.logger.messages[2]).must_match(%r{OpenTelemetry error: hi - bar - .+/opentelemetry_test\.rb:\d+:in .+'})
     end
 
     it 'calls user specified error handler' do

exporter/jaeger/thrift/zipkincore.thrift

@@ -292,7 +292,7 @@ struct Span {
   3: string name,
   4: i64 id,                       # unique span id, only used for this span
   5: optional i64 parent_id,       # parent span id
-  6: list<Annotation> annotations, # all annotations/events that occured, sorted by timestamp
+  6: list<Annotation> annotations, # all annotations/events that occurred, sorted by timestamp
   8: list<BinaryAnnotation> binary_annotations # any binary annotations
   9: optional bool debug = 0       # if true, we DEMAND that this span passes all samplers
   /**
@@ -302,7 +302,7 @@ struct Span {
    * precise value possible. For example, gettimeofday or syncing nanoTime
    * against a tick of currentTimeMillis.
    *
-   * For compatibilty with instrumentation that precede this field, collectors
+   * For compatibility with instrumentation that precede this field, collectors
    * or span stores can derive this via Annotation.timestamp.
    * For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp.
    *
@@ -317,7 +317,7 @@ struct Span {
    * precise measurement decoupled from problems of clocks, such as skew or NTP
    * updates causing time to move backwards.
    *
-   * For compatibilty with instrumentation that precede this field, collectors
+   * For compatibility with instrumentation that precede this field, collectors
    * or span stores can derive this by subtracting Annotation.timestamp.
    * For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp.
    *

exporter/otlp-metrics/README.md

@@ -121,7 +121,7 @@ The `opentelemetry-exporter-otlp-metrics` gem is distributed under the Apache 2.
 
 ## Working with Proto Definitions
 
-The OTel community maintains a [repository with protobuf definitions][otel-proto-github] that language and collector implementors use to generate code.
+The OTel community maintains a [repository with protobuf definitions][otel-proto-github] that language and collector implementers use to generate code.
 
 Maintainers are expected to keep up to date with the latest version of protos. This guide will provide you with step-by-step instructions on updating the OTLP Exporter gem with the latest definitions.
 

exporter/otlp/README.md

@@ -99,7 +99,7 @@ The `opentelemetry-exporter-otlp` gem is distributed under the Apache 2.0 licens
 
 ## Working with Proto Definitions
 
-The OTel community maintains a [repository with protobuf definitions][otel-proto-github] that language and collector implementors use to generate code.
+The OTel community maintains a [repository with protobuf definitions][otel-proto-github] that language and collector implementers use to generate code.
 
 Maintainers are expected to keep up to date with the latest version of protos. This guide will provide you with step-by-step instructions on updating the OTLP Exporter gem with the latest definitions.
 
@@ -138,7 +138,7 @@ $> bundle exec rake test
 
 ```
 
-**Commit the chnages and open a PR!**
+**Commit the changes and open a PR!**
 
 [opentelemetry-collector-home]: https://opentelemetry.io/docs/collector/about/
 [opentelemetry-home]: https://opentelemetry.io

exporter/zipkin/lib/opentelemetry/exporter/zipkin/exporter.rb

@@ -135,7 +135,7 @@ def send_spans(zipkin_spans, timeout: nil) # rubocop:disable Metrics/MethodLengt
 
             response = measure_request_duration { @http.request(request) }
             response.body # Read and discard body
-            # in opentelemetry-js 200-399 is succcess, in opentelemetry-collector zipkin exporter,200-299 is a success
+            # in opentelemetry-js 200-399 is success, in opentelemetry-collector zipkin exporter,200-299 is a success
             # zipkin api docs list 202 as default success code
             # https://zipkin.io/zipkin-api/#/default/post_spans
             # TODO: redirect

exporter/zipkin/lib/opentelemetry/exporter/zipkin/transformer.rb

@@ -50,7 +50,7 @@ def to_zipkin_span(span_d, resource)
           add_status_tags(span_d, tags)
           tags = aggregate_span_tags(span_d, tags)
 
-          # TOOO: set debug flag? (is that represented in tracestate?)
+          # TODO: set debug flag? (is that represented in tracestate?)
           # https://github.com/openzipkin/b3-propagation#why-is-debug-encoded-as-x-b3-flags-1
           # https://github.com/openzipkin/zipkin-api/blob/7692ca7be4dc3be9225db550d60c4d30e6e9ec59/zipkin2-api.yaml#L475
           # TODO: shared key mapping

logs_sdk/lib/opentelemetry/sdk/logs/export.rb

@@ -7,8 +7,10 @@
 module OpenTelemetry
   module SDK
     module Logs
-      # The Export module contains result codes for exporters
+      # The Export module contains the built-in exporters and log record
+      # processors for the OpenTelemetry reference implementation.
       module Export
+        ExportError = Class.new(OpenTelemetry::Error)
         # The operation finished successfully.
         SUCCESS = 0
 
@@ -21,3 +23,5 @@ module Export
     end
   end
 end
+
+require_relative 'export/log_record_exporter'

logs_sdk/lib/opentelemetry/sdk/logs/export/log_record_exporter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      module Export
+        # LogRecordExporter describes a duck type. It is not required to
+        # subclass this class to provide an implementation of LogRecordExporter,
+        # provided the interface is satisfied. LogRecordExporter allows
+        # different tracing services to export log record data in their own format.
+        #
+        # To export data an exporter MUST be registered to the {LoggerProvider}
+        # using a {LogRecordProcessor} implementation.
+        class LogRecordExporter
+          def initialize
+            @stopped = false
+          end
+
+          # Called to export {LogRecordData}s.
+          #
+          # @param [Enumerable<LogRecordData>] log_record_data the list of
+          # {LogRecordData} to be exported.
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          #
+          # @return [Integer] the result of the export.
+          def export(log_record_data, timeout: nil)
+            return SUCCESS unless @stopped
+
+            FAILURE
+          end
+
+          # Called when {LoggerProvider#force_flush} is called, if this exporter is
+          # registered to a {LoggerProvider} object.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          # @return [Integer] SUCCESS if no error occurred, FAILURE if a
+          #   non-specific failure occurred, TIMEOUT if a timeout occurred.
+          def force_flush(timeout: nil)
+            SUCCESS
+          end
+
+          # Called when {LoggerProvider#shutdown} is called, if this exporter is
+          # registered to a {LoggerProvider} object.
+          #
+          # @param [optional Numeric] timeout An optional timeout in seconds.
+          def shutdown(timeout: nil)
+            @stopped = true
+            SUCCESS
+          end
+        end
+      end
+    end
+  end
+end

logs_sdk/lib/opentelemetry/sdk/logs/log_record.rb

@@ -45,7 +45,7 @@ class LogRecord < OpenTelemetry::Logs::LogRecord
         #   current context.
         # @param [optional OpenTelemetry::Trace::TraceFlags] trace_flags The
         #   trace flags associated with the current context.
-        # @param [optional OpenTelemetry::SDK::Resources::Resource] recource The
+        # @param [optional OpenTelemetry::SDK::Resources::Resource] resource The
         #   source of the log, desrived from the LoggerProvider.
         # @param [optional OpenTelemetry::SDK::InstrumentationScope] instrumentation_scope
         #   The instrumentation scope, derived from the emitting Logger

logs_sdk/test/opentelemetry/sdk/logs/export/log_record_exporter_test.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'test_helper'
+
+describe OpenTelemetry::SDK::Logs::Export::LogRecordExporter do
+  export = OpenTelemetry::SDK::Logs::Export
+
+  let(:log_record_data1) { OpenTelemetry::SDK::Logs::LogRecordData.new({ name: 'name1' }) }
+  let(:log_record_data2) { OpenTelemetry::SDK::Logs::LogRecordData.new({ name: 'name2' }) }
+  let(:log_records)      { [log_record_data1, log_record_data2] }
+  let(:exporter)         { export::LogRecordExporter.new }
+
+  it 'accepts an Array of LogRecordData as arg to #export and succeeds' do
+    _(exporter.export(log_records)).must_equal export::SUCCESS
+  end
+
+  it 'accepts an Enumerable of LogRecordData as arg to #export and succeeds' do
+    enumerable = Struct.new(:log_record0, :log_record1).new(log_records[0], log_records[1])
+
+    _(exporter.export(enumerable)).must_equal export::SUCCESS
+  end
+
+  it 'accepts calls to #shutdown' do
+    exporter.shutdown
+  end
+
+  it 'fails to export after shutdown' do
+    exporter.shutdown
+    _(exporter.export(log_records)).must_equal export::FAILURE
+  end
+
+  it 'returns SUCCESS when #force_flush is called' do
+    assert(export::SUCCESS, exporter.force_flush)
+  end
+end