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:
You can see more at the OpenTelemetry website.
Installation
-
Add the dependency to your
shard.yml
:dependencies: opentelemetry: github: jgaskins/opentelemetry
-
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.
"x-honeycomb-dataset" => ENV["HONEYCOMB_DATASET"],
},
)
)
end
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
- Fork it (https://github.com/jgaskins/opentelemetry/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- Jamie Gaskins - creator and maintainer