• Stars
    star
    212
  • Rank 186,122 (Top 4 %)
  • Language
    Ruby
  • License
    MIT License
  • Created almost 11 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Ruby on Rails bindings to automatically write metrics into InfluxDB

⚠️ You are looking at the README a development branch of this gem. If you are using this gem you should have a look at the latest released version (1.0.3) instead.

influxdb-rails

Gem Version Build Status

Automatically instrument your Ruby on Rails applications and write the metrics directly into InfluxDB.

Table of contents

Installation

Add the gem to your Gemfile:

echo 'gem "influxdb-rails"' >> Gemfile
bundle install

To get things set up, create an initializer:

bundle exec rails generate influxdb

This creates a file config/initializers/influxdb_rails.rb, which allows configuration of this gem.

Usage

Out of the box, you'll automatically get reporting for the Ruby on Rails components mentioned below.

Action Controller

Reported ActiveSupport instrumentation hooks:

Reported fields:

  controller: 48.467,
  view: 46.848,
  db: 0.157,
  started: 1465839830100400200,
  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"

Reported tags:

{
  hook:        "process_action",
  server:      Socket.gethostname,
  app_name:    configuration.application_name,
  method:      "PostsController#index",
  http_method: "GET",
  format:      "html",
  status:      ["500"],
  exception:   "ArgumentError"
}

Action View

Reported ActiveSupport instrumentation hooks:

Reported fields:

  value: 48.467,
  count: 3,
  cache_hits: 0,
  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"

Reported tags:

  hook:       ["render_template", "render_partial", "render_collection"],
  server:     Socket.gethostname,
  app_name:   configuration.application_name,
  location:   "PostsController#index",
  filename:   "/some/file/action.html"

Active Record

Reported ActiveSupport instrumentation hooks:

Reported fields:

  sql: "SELECT \"posts\".* FROM \"posts\"",
  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"

Reported SQL tags:

  hook:       "sql",
  server:     Socket.gethostname,
  app_name:   configuration.application_name,
  location:   "PostsController#index",
  operation:  "SELECT",
  class_name: "POST",
  name:       "Post Load"

Reported instantiation values:

  record_count: 1,
  request_id:   "d5bf620b-3494-425b-b7e1-4953597ea744"
  value:        7.689

Reported instantiation tags:

  hook:       "instantiation",
  server:     Socket.gethostname,
  app_name:   configuration.application_name,
  location:   "PostsController#index",
  class_name: "POST"

Active Job

Reported ActiveSupport instrumentation hooks:

Reported fields:

  value: 89.467

Reported tags:

  hook:       ["enqueue", "perform"],
  state:      ["queued", "succeeded", "failed"],
  job:        "SomeJobClassName",
  queue:      "queue_name"

Note: Only the measurements with the hook perform report a duration in the value. The enqueue hook is a counter and always reports a value of 1.

Action Mailer

Reported ActiveSupport instrumentation hooks:

Reported fields:

  value: 1

Reported tags:

  hook:               "deliver",
  mailer:             "SomeMailerClassName"

Note: The hook is just a counter and always report a value of 1.

Configuration

The only settings you actually need to configure are the organization, bucket and access token.

InfluxDB::Rails.configure do |config|
  config.client.org = "org"
  config.client.bucket = "bucket"
  config.client.token = "token"
end

You'll find all of the configuration settings in the initializer file.

Custom Tags

You can modify the tags sent to InfluxDB by defining a middleware, which receives the current tag set as argument and returns a hash in the same form. The middleware can be any object, as long it responds to #call (like a Proc):

InfluxDB::Rails.configure do |config|
  config.tags_middleware = lambda do |tags|
    tags.merge(env: Rails.env)
  end
end

The tags argument is a Hash (mapping Symbol keys to String values). The actual keys and values depend on the series name (tags[:series], see next section).

If you want to add dynamically tags or fields per request, you can access InfluxDB::Rails.current to do so. For instance, you could add the current user as tag or redis query time to every data point:

class ApplicationController
  before_action :set_influx_data

  def set_influx_data
    InfluxDB::Rails.current.tags = { user: current_user.id }
    InfluxDB::Rails.current.fields = { redis_value: redis_value }
  end
end

Block Instrumentation

If you want to add custom instrumentation, you can wrap any code into a block instrumentation

InfluxDB::Rails.instrument "expensive_operation", tags: { }, fields: { } do
  expensive_operation
end

Reported tags:

  hook:       "block_instrumentation",
  server:     Socket.gethostname,
  app_name:   configuration.application_name,
  location:   "PostsController#index",
  name:       "expensive_operation"

Reported fields:

  value: 100 # execution time of the block in ms

You can also overwrite the value

InfluxDB::Rails.instrument "user_count", fields: { value: 1 } do
  User.create(name: 'mickey', surname: 'mouse')
end

or call it even without a block

InfluxDB::Rails.instrument "temperature", fields: { value: 25 }

Custom client configuration

The settings named config.client.* are used to construct an InfluxDB::Client instance, which is used internally to transmit the reporting data points to your InfluxDB server. You can access this client as well, and perform arbitrary operations on your data:

InfluxDB::Rails.write_api.write(
  name: "events",
  tags:   { url: "/foo", user_id: current_user.id, location: InfluxDB::Rails.current.location },
  fields: { value: 0 }
)

If you do that, it might be useful to add the current context to these custom data points which can get accessed with InfluxDB::Rails.current.location.

See influxdb-client for a full list of configuration options and detailed usage.

Disabling hooks

If you are not interested in certain reports you can disable them in the configuration.

InfluxDB::Rails.configure do |config|
  config.ignored_hooks = ['sql.active_record', 'render_template.action_view']
end

Demo

Want to see this in action? Check out our sample dashboard.

Frequently Asked Questions

I'm seeing far less requests recorded in InfluxDB than my logs suggest.

By default, this gem writes data points with millisecond time precision to the InfluxDB server. If you have more than 1000 requests/second (and/or multiple parallel requests), only the last data point (within the same tag set) is stored. See InfluxDB server docs for further details.

To work around this limitation, set the config.client.time_precision to one of "us" (microseconds, 1Β·10-6s) or "ns" (nanoseconds, 1Β·10-9s).

Please note: This will only ever reduce the likelihood of data points overwriting each other, but not eliminate it completely.

How does the measurement influence the response time?

This gem subscribes to various ActiveSupport::Notifications hooks. (cf. guide Β· docs Β· impl). The controller notifications are run after a controller action has finished, and should not impact the response time.

Other notification hooks (rendering and SQL queries) run inline in the request processing. The amount of overhead introduced should be negligible, though. However reporting of SQL queries relies on Ruby string parsing which might cause performance issues on traffic intensive applications. Disable it in the configuration if you are not willing to tolerate this.

By default, this gem performs writes to InfluxDB asynchronously. A single hook usually only performs some time delta calculations, and then enqueues the data point into a worker queue (which is processed by a background thread).

If you, however, use a synchronous client (config.client.async = false), the data points are immediately sent to the InfluxDB server. Depending on the network link, this might cause the HTTP thread to block a lot longer.

How does this gem handle an unreachable InfluxDB server?

By default, the InfluxDB client will retry indefinitely, until a write succeeds (see client docs for details). This has two important implications, depending on the value of config.client.async:

  • if the client runs asynchronously (i.e. in a separate thread), the queue might fill up with hundreds of megabytes of data points
  • if the client runs synchronously (i.e. inline in the request/response cycle), it might block all available request threads

In both cases, your application server might become unresponsive and needs to be restarted.

If you setup a maximum retry value (Integer === config.client.retry), the client will try up to that amount of times to send the data to the server and (on final error) log an error and discard the values.

What happens, when the InfluxDB client or this gem throws an exception? Will the user see 500 errors?

No. The controller instrumentation is wrapped in a rescue StandardError clause, i.e. this gem will only write the error to the client.logger (Rails.logger by default) and not disturb the user experience.

What happens with unwritten points, when the application restarts?

The data points are simply discarded.

Contributing

  • Fork this repository on GitHub
  • Make your changes
    • Add tests.
    • Add an entry in the CHANGELOG.md in the "unreleased" section on top.
  • Run the tests:
    • Either run them manually:

      rake test:all
    • or wait for our CI to pick up your changes, after you made a pull request.

  • Send a pull request.
  • If your changes are looking good, we'll merge them.

Testing Tasks

rake            # unit tests + Rubocop linting
rake spec       # only unit tests
rake rubocop    # only Rubocop linter
rake test:all   # integration tests with various Rails version

More Repositories

1

influxdb

Scalable datastore for metrics, events, and real-time analytics
Rust
28,401
star
2

telegraf

Agent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.
Go
14,568
star
3

kapacitor

Open source framework for processing, monitoring, and alerting on time series data
Go
2,310
star
4

influxdb-python

Python client for InfluxDB
Python
1,689
star
5

chronograf

Open source monitoring and visualization UI for the TICK stack
TypeScript
1,480
star
6

influxdb-java

Java client for InfluxDB
Java
1,178
star
7

influxdb-relay

Service to replicate InfluxDB data for high availability
Python
830
star
8

flux

Flux is a lightweight scripting language for querying databases (like InfluxDB) and working with data. It's part of InfluxDB 1.7 and 2.0, but can be run independently of those.
FLUX
767
star
9

influxdb-client-python

InfluxDB 2.0 python client
Python
709
star
10

influxdb-client-go

InfluxDB 2 Go Client
Go
599
star
11

go-syslog

Blazing fast syslog parser
Go
478
star
12

sandbox

A sandbox for the full TICK stack
Shell
475
star
13

influxdb-client-java

InfluxDB 2 JVM Based Clients
Java
433
star
14

influxdb-php

influxdb-php: A PHP Client for InfluxDB, a time series database
PHP
431
star
15

influxdb-client-csharp

InfluxDB 2.x C# Client
C#
357
star
16

community-templates

InfluxDB Community Templates: Quickly collect & analyze time series data from a range of sources: Kubernetes, MySQL, Postgres, AWS, Nginx, Jenkins, and more.
Python
350
star
17

influxdb-client-js

InfluxDB 2.0 JavaScript client
TypeScript
326
star
18

influxdata-docker

Official docker images for the influxdata stack
Shell
314
star
19

influxdb-comparisons

Code for comparison write ups of InfluxDB and other solutions
Go
306
star
20

rskafka

A minimal Rust client for Apache Kafka
Rust
292
star
21

docs.influxdata.com-ARCHIVE

ARCHIVE - 1.x docs for InfluxData
Less
252
star
22

helm-charts

Official Helm Chart Repository for InfluxData Applications
Mustache
226
star
23

influxdb-csharp

A .NET library for efficiently sending points to InfluxDB 1.x
C#
198
star
24

influxdb1-client

The old clientv2 for InfluxDB 1.x
Go
190
star
25

giraffe

A foundation for visualizations in the InfluxDB UI
TypeScript
183
star
26

influxql

Package influxql implements a parser for the InfluxDB query language.
Go
168
star
27

influxdb-client-php

InfluxDB (v2+) Client Library for PHP
PHP
149
star
28

tdigest

An implementation of Ted Dunning's t-digest in Go.
Go
133
star
29

influx-stress

New tool for generating artificial load on InfluxDB
Go
118
star
30

ui

UI for InfluxDB
TypeScript
93
star
31

tick-charts

A repository for Helm Charts for the full TICK Stack
Smarty
90
star
32

pbjson

Auto-generate serde implementations for prost types
Rust
89
star
33

telegraf-operator

telegraf-operator helps monitor application on Kubernetes with Telegraf
Go
80
star
34

inch

An InfluxDB benchmarking tool.
Go
78
star
35

influxdata-operator

A k8s operator for InfluxDB
Go
76
star
36

docs-v2

InfluxData Documentation that covers InfluxDB Cloud, InfluxDB OSS 2.x, InfluxDB OSS 1.x, InfluxDB Enterprise, Telegraf, Chronograf, Kapacitor, and Flux.
SCSS
72
star
37

wirey

Manage local wireguard interfaces in a distributed system
Go
66
star
38

influx-cli

CLI for managing resources in InfluxDB v2
Go
63
star
39

influxdb-go

61
star
40

terraform-aws-influx

Reusable infrastructure modules for running TICK stack on AWS
HCL
51
star
41

influxdb2-sample-data

Sample data for InfluxDB 2.0
JavaScript
46
star
42

influxdb-observability

Go
46
star
43

influxdb-client-ruby

InfluxDB 2.0 Ruby Client
Ruby
45
star
44

clockface

UI Kit for building Chronograf
TypeScript
44
star
45

grade

Track Go benchmark performance over time by storing results in InfluxDB
Go
43
star
46

influxdb-r

R library for InfluxDB
R
43
star
47

nginx-influxdb-module

C
39
star
48

nifi-influxdb-bundle

InfluxDB Processors For Apache NiFi
Java
36
star
49

line-protocol

Go
36
star
50

tensorflow-influxdb

Jupyter Notebook
34
star
51

iot-center-flutter

InlfuxDB 2.0 dart client flutter demo
Dart
34
star
52

whisper-migrator

A tool for migrating data from Graphite Whisper files to InfluxDB TSM files (version 0.10.0).
Go
33
star
53

flightsql-dbapi

DB API 2 interface for Flight SQL with SQLAlchemy extras.
Python
32
star
54

kube-influxdb

Configuration to monitor Kubernetes with the TICK stack
Shell
31
star
55

k8s-kapacitor-autoscale

Demonstration of using Kapacitor to autoscale a k8s deployment
Go
30
star
56

terraform-aws-influxdb

Deploys InfluxDB Enterprise to AWS
HCL
29
star
57

catslack

Shell -> Slack the easy way
Go
28
star
58

flux-lsp

Implementation of Language Server Protocol for the flux language
Rust
27
star
59

influxdb-operator

The Kubernetes operator for InfluxDB and the TICK stack.
Go
27
star
60

influxdb3_core

InfluxData's core functionality for InfluxDB Edge and IOx
Rust
26
star
61

influxdb-client-swift

InfluxDB (v2+) Client Library for Swift
Swift
26
star
62

influxdb-client-dart

InfluxDB (v2+) Client Library for Dart and Flutter
Dart
25
star
63

kapacitor-course

25
star
64

influxdb-c

C
25
star
65

vsflux

Flux language extension for VSCode
TypeScript
25
star
66

grafana-flightsql-datasource

Grafana plugin for Flight SQL APIs.
TypeScript
25
star
67

ansible-chrony

A role to manage chrony on Linux systems
Ruby
24
star
68

influxdb-scala

Scala client for InfluxDB
Scala
22
star
69

cron

A fast, zero-allocation cron parser in ragel and golang
Go
21
star
70

influxdb-plugin-fluent

A buffered output plugin for Fluentd and InfluxDB 2
Ruby
21
star
71

terraform-google-influx

Reusable infrastructure modules for running TICK stack on GCP
Shell
20
star
72

iot-api-python

Python
18
star
73

openapi

An OpenAPI specification for influx (cloud/oss) apis.
Shell
17
star
74

influxdb-university

InfluxDB University
Python
16
star
75

influxdb-client-r

InfluxDB (v2+) Client R Package
R
14
star
76

kafka-connect-influxdb

InfluxDB 2 Connector for Kafka
Scala
13
star
77

cd-gitops-reference-architecture

Details of the CD/GitOps architecture in use at InfluxData
Shell
13
star
78

iot-api-ui

Common React UI for iot-api-<js, python, etc.> example apps designed for InfluxDB client library tutorials.
TypeScript
13
star
79

oats

An OpenAPI to TypeScript generator.
TypeScript
12
star
80

awesome

SCSS
12
star
81

windows-packager

Create a windows installer
Shell
12
star
82

influxdb-gds-connector

Google Data Studio Connector for InfluxDB.
JavaScript
11
star
83

promql

Go
11
star
84

object_store_rs

Rust
10
star
85

yarpc

Yet Another RPC for Go
Go
10
star
86

ansible-influxdb-enterprise

Ansible role for deploying InfluxDB Enterprise.
10
star
87

influxdb-sample-data

Sample time series data used to test InfluxDB
9
star
88

ingen

ingen is a tool for directly generating TSM data
Go
9
star
89

parquet-bloom-filter-analysis

Generate Parquet Files
Rust
8
star
90

ansible-kapacitor

Official Kapacitor Ansible Role for Linux
Jinja
7
star
91

wlog

Simple log level based Go logger.
Go
7
star
92

iot-api-js

An example IoT app built with NextJS (NodeJS + React) and the InfluxDB API client library for Javascript.
JavaScript
7
star
93

influxdb-iox-client-go

InfluxDB/IOx Client for Go
Go
7
star
94

influxdb-templates

This repo is a collection of dashboard templates used in the InfluxDB UI.
JavaScript
7
star
95

k8s-jsonnet-libs

Jsonnet Libs repo - mostly generated with jsonnet-libs/k8s project
Jsonnet
7
star
96

google-deployment-manager-influxdb-enterprise

GCP Deployment Manager templates for InfluxDB Enterprise.
HTML
6
star
97

jaeger-influxdb

Go
6
star
98

influxdb-action

A GitHub action for setting up and configuring InfluxDB and the InfluxDB Cloud CLI
Shell
6
star
99

influxdb-fsharp

A F# client library for InfluxDB, a time series database http://influxdb.com
F#
6
star
100

qprof

A tool for profiling the performance of InfluxQL queries
Go
6
star