Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/census-instrumentation/opencensus-ruby

A stats collection and distributed tracing framework
https://github.com/census-instrumentation/opencensus-ruby

Last synced: 3 months ago
JSON representation

A stats collection and distributed tracing framework

Lists

README 

        
> **Warning**

>

> OpenCensus and OpenTracing have merged to form [OpenTelemetry](https://opentelemetry.io), which serves as the next major version of OpenCensus and OpenTracing.

>

> OpenTelemetry has now reached feature parity with OpenCensus, with tracing and metrics SDKs available in .NET, Golang, Java, NodeJS, and Python. **All OpenCensus Github repositories, except [census-instrumentation/opencensus-python](https://github.com/census-instrumentation/opencensus-python), will be archived on July 31st, 2023**. We encourage users to migrate to OpenTelemetry by this date.

>

> To help you gradually migrate your instrumentation to OpenTelemetry, bridges are available in Java, Go, Python, and JS. [**Read the full blog post to learn more**](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).



# OpenCensus - A stats collection and distributed tracing framework



This is the open-source release of Census for Ruby. Census provides a

framework to measure a server's resource usage and collect performance stats.



This repository contains the source to the `opencensus` Rubygem, which contains

the core OpenCensus APIs and basic integrations with Rails, Faraday, and GRPC.

Additional integrations, including exporters to popular analytics services,

will be available in separate gems.



The library is in alpha stage, and the API is subject to change. In particular,

support for the Stats API is currently incomplete and experimental.



## Quick Start



### Installation



Install the gem directly:



```sh

$ gem install opencensus

```



Or install through Bundler:



1. Add the `opencensus` gem to your Gemfile:



```ruby

gem "opencensus"

```



2. Use Bundler to install the gem:



```sh

$ bundle install

```



### Getting started with Ruby on Rails



The OpenCensus library provides a Railtie that integrates with Ruby On Rails,

automatically tracing incoming requests in the application. It also

automatically traces key processes in your application such as database queries

and view rendering.



To enable Rails integration, require this file during application startup:



```ruby

# In config/application.rb

require "opencensus/trace/integrations/rails"

```



See the documentation for the

[Rails integration class](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Integrations/Rails)

for more information.



### Getting started with other Rack-based frameworks



Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware

integration, which automatically traces incoming requests. To enable the

integration for a non-Rails Rack framework, add the middleware to your

middleware stack.



```ruby

# In config.ru or similar Rack configuration file

require "opencensus/trace/integrations/rack_middleware"

use OpenCensus::Trace::Integrations::RackMiddleware

```



## Instrumentation features



### Tracing outgoing HTTP requests



If your app uses the [Faraday](https://github.com/lostisland/faraday) library

to make outgoing HTTP requests, consider installing the Faraday Middleware

integration. This integration creates a span for each outgoing Faraday request,

tracking the latency of that request, and propagates distributed trace headers

into the request so you can potentially connect your request trace with that of

the remote service. Here is an example:



```ruby

require "opencensus/trace/integrations/rack_middleware"

conn = Faraday.new(url: "http://www.example.com") do |c|

  c.use OpenCensus::Trace::Integrations::FaradayMiddleware

  c.adapter Faraday.default_adapter

end

conn.get "/"

```



See the documentation for the

[FaradayMiddleware](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Integrations/FaradayMiddleware)

class for more info.



### Adding Custom Trace Spans



In addition to the spans added by the Rails integration (e.g. for database

queries) and by Faraday integration for outgoing HTTP requests, you can add

additional custom spans to the request trace:



```ruby

OpenCensus::Trace.in_span "my_task" do |span|

  # Do stuff...

  

  OpenCensus::Trace.in_span "my_subtask" do |subspan|

    # Do other stuff

  end

end

```



See the documentation for the

[OpenCensus::Trace](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace)

module for more info.



### Exporting traces



By default, OpenCensus will log request trace data as JSON. To export traces to

your favorite analytics backend, install an export plugin. 



The provided exporters are:



| Class | Description |

| ----- | ----------- |

| [LoggerExporter][logger-exporter] | Exporter JSON encoded spans to a standard Ruby Logger interface |

| [StackdriverExporter][stackdriver-exporter] | Report traces to Google Cloud Stackdriver Trace |

| [ZipkinExporter][zipkin-exporter] | Report collected spans to a Zipkin server |



You may also create your own

[Exporter](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Exporters)



### Configuring the library



OpenCensus allows configuration of a number of aspects via the configuration

class. The following example illustrates how that looks:



```ruby

OpenCensus.configure do |c|

  c.trace.default_sampler = OpenCensus::Trace::Samplers::AlwaysSample.new

  c.trace.default_max_attributes = 16

end

```



If you are using Rails, you can equivalently use the Rails config:



```ruby

config.opencensus.trace.default_sampler =

  OpenCensus::Trace::Samplers::AlwaysSample.new

config.opencensus.trace.default_max_attributes = 16

```



You can configure a variety of core OpenCensus options, including:



* Sampling, which controls how often a request is traced.

* Exporting, which controls how trace information is reported.

* Formatting, which controls how distributed request trace headers are

  constructed

* Size maximums, which control when trace data is truncated.



Additionally, integrations and other plugins might have their own

configurations.



For more information, consult the documentation for

[OpenCensus.configure](http://www.rubydoc.info/gems/opencensus/OpenCensus#configure-class_method)

and

[OpenCensus::Trace.configure](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace#configure-class_method).



## About the library



### Supported Ruby Versions



This library is supported on Ruby 2.2+.



However, Ruby 2.3 or later is strongly recommended, as earlier releases have

reached or are nearing end-of-life. After June 1, 2018, OpenCensus will provide

official support only for Ruby versions that are considered current and

supported by Ruby Core (that is, Ruby versions that are either in normal

maintenance or in security maintenance).

See https://www.ruby-lang.org/en/downloads/branches/ for further details.



### Versioning



This library follows [Semantic Versioning](http://semver.org/).



It is currently in major version zero (0.y.z), which means that anything may

change at any time, and the public API should not be considered stable.



## Contributing



Contributions to this library are always welcome and highly encouraged.



See the [Contributing Guide](CONTRIBUTING.md) for more information on how to get

started.



Please note that this project is released with a Contributor Code of Conduct. By

participating in this project you agree to abide by its terms. See

[Code of Conduct](CODE_OF_CONDUCT.md) for more information.



## License



This library is licensed under Apache 2.0. Full license text is available in

[LICENSE](LICENSE).



## Disclaimer



This is not an official Google product.



[logger-exporter]: https://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Exporters/Logger

[stackdriver-exporter]: https://github.com/census-ecosystem/opencensus-ruby-exporter-stackdriver

[zipkin-exporter]: https://github.com/census-ecosystem/opencensus-ruby-exporter-zipkin