https://github.com/dmathieu/rspec-otel
RSpec matchers for the OpenTelemetry framework
https://github.com/dmathieu/rspec-otel
opentelemetry rspec ruby
Last synced: 2 months ago
JSON representation
RSpec matchers for the OpenTelemetry framework
- Host: GitHub
- URL: https://github.com/dmathieu/rspec-otel
- Owner: dmathieu
- License: mit
- Created: 2024-02-13T10:00:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-04-14T11:59:00.000Z (2 months ago)
- Last Synced: 2026-04-14T12:13:23.844Z (2 months ago)
- Topics: opentelemetry, rspec, ruby
- Language: Ruby
- Homepage:
- Size: 266 KB
- Stars: 4
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# RSpec Otel
RSpec matchers to be used with the OpenTelemetry framework
## Installation
Add this line to your Gemfile:
```ruby
gem 'rspec-otel'
```
Within your spec helper, require the gem:
```ruby
require 'rspec_otel'
```
And include the matchers within the rspec configuration:
```ruby
RSpec.configure do |config|
config.include RspecOtel::Matchers
end
```
## Usage
### Matching the presence of a span
You can match the emission of a span with the `emit_span` matcher:
```ruby
require 'spec_helper'
RSpec.describe 'User API' do
it 'emits a span' do
expect do
get :user, id: 1
end.to emit_span('GET /user')
end
end
```
`emit_span` will also match a regular expression:
```ruby
require 'spec_helper'
RSpec.describe 'User API' do
it 'emits a span' do
expect do
get :user, id: 1
end.to emit_span(/^GET /)
end
end
```
Several conditions can be added to the matcher:
* `as_root` - Will match spans that are the root of a trace.
* `as_child` - Will match spans that are not the root of a trace
* `with_attributes` - Will match only the spans with the specified attributes.
* `without_attributes` - Will only match the spans that do not have the specified attributes
* `with_event` - Will match only the spans with the specified event.
* `without_event` - Will only match the spans that do not have the specified event
* `with_link` - Will match only the spans with the specified link.
* `without_link` - Will only match the spans that do not have the specified link
* `with_status` - Will match only the spans that have the proper status.
* `with_exception` - Will match only the spans that have the specified exception event.
* `without_exception` - Will match only the spans that do not have the specified exception event.
_The `*_event` condition can be called multiple times with different events._
### Matching the presence of a metric
You can match the emission of a metric with the `emit_metric` matcher:
```ruby
require 'spec_helper'
RSpec.describe 'User API' do
it 'emits a metric' do
expect do
get :user, id: 1
end.to emit_metric('http.server.duration')
end
end
```
`emit_metric` will also match a regular expression:
```ruby
expect do
get :user, id: 1
end.to emit_metric(/^http\.server\./)
```
Several conditions can be added to the matcher:
* `of_type` - Will match only metrics of the specified instrument kind (`:counter`, `:histogram`, `:gauge`, `:up_down_counter`, `:observable_counter`, `:observable_gauge`, `:observable_up_down_counter`).
* `with_attributes` - Will match only the metrics with the specified attributes on a data point.
* `without_attributes` - Will only match the metrics that do not have the specified attributes on any data point.
* `with_value` - Will match only the metrics where a data point has the specified value (applies to counters, gauges, and up-down counters).
* `with_count` - Will match only the metrics where a histogram data point has the specified recording count (applies to histograms only).
```ruby
expect do
get :user, id: 1
end.to emit_metric('http.server.duration')
.of_type(:histogram)
.with_attributes({ 'http.request.method' => 'GET' })
```
### Disabling
We wrap every example in a new OpenTelemetry SDK configuration by default, if you wish to disable this you can tag your example with `:rspec_otel_disable_tracing`:
```ruby
require 'spec_helper'
RSpec.describe 'User API', :rspec_otel_disable_tracing do
it 'tests my code' do
expect(true).to be true
end
end
```
## Compatibility
RSpec Otel ensures compatibility with the currently supported versions of the
[Ruby Language](https://www.ruby-lang.org/en/downloads/branches/).