OpenTelemetry

OpenTelemetry is an observability framework for cloud-native software.

This Crystal shard allows you to add it to your applications to export application telemetry to OpenTelemetry-compatible services, such as:

• Honeycomb
• Datadog
• Prometheus
• New Relic
• Lightstep

You can see more at the OpenTelemetry website.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     opentelemetry:
       github: jgaskins/opentelemetry
   

2. Run shards install

Usage

To use this shard, you'll need to have a service setup to receive OpenTelemetry data. In this example, we'll use Honeycomb:

require "opentelemetry"

OpenTelemetry.configure do |c|
  c.exporter = OpenTelemetry::BatchExporter.new(
    OpenTelemetry::HTTPExporter.new(
      endpoint: URI.parse("https://api.honeycomb.io"),
      headers: HTTP::Headers{
        # Get your Honeycomb API key from https://ui.honeycomb.io/account
        "x-honeycomb-team"    => ENV["HONEYCOMB_API_KEY"],
        # Name this whatever you like. Honeycomb will create the dataset when it
        # begins reporting data in Honeycomb Classic accounts
        "x-honeycomb-dataset" => ENV["HONEYCOMB_DATASET"],
      },
    )
  )
end

Note: The shard supports using OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES environment variables to populate the trace's associated resource (dataset in the Honeycomb example above).

Instrumenting

Use the OpenTelemetry.trace method to create a new trace for the current fiber or to add a span inside the current trace.

OpenTelemetry.trace "outer-span" do |span|
  span["my-attribute"] = "my value"
  # do some work

  OpenTelemetry.trace "inner-span" do |span|
    span["another-attribute"] = "another value"
    # do some work
  end

  # do some work
end

HTTP::Server middleware

If you are instrumenting a Crystal web app, you will want to add a OpenTelemetry::Middleware instance to your server middleware stack, passing in the name of the root span.

http = HTTP::Server.new([
  # ...
  OpenTelemetry::Middleware.new("http.server.request"),
  # ...
])

Integrations

You enable many integrations simply by requiring them. They will be instrumented automatically.

# Load the integration for the crystal-lang/crystal-db shard
require "opentelemetry/integrations/db"

You can see all of the integrations available in the integrations directory.

Contributing

1. Fork it (https://github.com/jgaskins/opentelemetry/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

Contributors

• Jamie Gaskins - creator and maintainer