Aspecto::OpenTelemetry

Aspecto's SDK for ruby.
This gem is a distribution of OpenTelemetry pre-configured to use all available instrumentations and export trace data to Aspecto.

Installation

Install the gem using:

$ gem install aspecto-opentelemetry

Or, if you use bundler, include aspecto-opentelemetry in your Gemfile.

Usage

Rails Applications

Add this code to a new file aspecto.rb under config/initializers/:

# config/initializers/aspecto.rb
require 'aspecto/opentelemetry'

Aspecto::OpenTelemetry::configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
  c.aspecto_auth = '<YOUR_ASPECTO_TOKEN>'
  # c.sampling_ratio = 1.0 # [optional]: defaults to 1.0, use aspecto app to configure remotely
end

Ruby Applications

Add this code after your require other gems:

require 'aspecto/opentelemetry'

Aspecto::OpenTelemetry::configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
  c.aspecto_auth = '<YOUR_ASPECTO_TOKEN>'
  # c.env = '<CURRENT_ENVIRONMENT>' # [optional]: automatically detected for rails and sinatra
  # c.sampling_ratio = 1.0 # [optional]: defaults to 1.0, use aspecto app to configure remotely
end

Shutdown

Call this function when your application shuts down

Aspecto::OpenTelemetry::shutdown

Configuration

You can set configuration via environment variables or via code. Values set in code takes precedence. The only required config options are aspecto_auth and service_name.

Configuration Options

Option Name	Environment Variable	Type	Default	Description
aspecto_auth	ASPECTO_AUTH	UUID string	-	Aspecto's API key for authentication
service_name	OTEL_SERVICE_NAME	string	-	Name of the service which is sending telemetry
env	ASPECTO_ENV	string	Extracted from Rails or Sinatra if used	Deployment environment: production / staging / development, etc.
log_level	OTEL_LOG_LEVEL	string	ERROR	ERROR / WARN / INFO, etc.
sampling_ratio	ASPECTO_SAMPLING_RATIO	float	1.0	How many of the traces starting in this service should be sampled. set to number in range [0.0, 1.0] where 0.0 is no sampling, and 1.0 is sample all
otel_exporter_otlp_traces_endpoint	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	URL	https://otelcol.aspecto.io/v1/trace	Url
require_config_for_traces	ASPECTO_REQUIRE_CONFIG_FOR_TRACES	boolean	false	When true, the SDK will not trace anything until remote sampling configuration arrives (few hundreds ms). Can be used to enforce sampling configuration is always applied, with the cost of losing traces generated during service startup.
extract_b3_context	ASPECTO_EXTRACT_B3_CONTEXT	boolean	false	Set to true when the service receives requests from another instrumented component that propagate context via B3 protocol multi or single header. For example: Envoy Proxy, Ambassador and Istio
inject_b3_context_single_header	ASPECTO_INJECT_B3_CONTEXT_SINGLE_HEADER	boolean	false	Set to true when the service send traffic to another instrumented component that propagate context via B3 single header protocol
inject_b3_context_multi_header	ASPECTO_INJECT_B3_CONTEXT_MULTI_HEADER	boolean	false	Set to true when the service send traffic to another instrumented component that propagate context via B3 multi header protocol. For example: Envoy Proxy, Istio

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/aspecto-io/aspecto-opentelemetry-ruby.