### Run exporter with custom configuration

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Example command to start the exporter with specific port, binding, timeout, labels, and prefix.

```bash
prometheus_exporter -p 8080 \
                    -b 0.0.0.0 \
                    -t 1 \
                    --label '{"environment": "integration", "foo": "bar"}' \
                    --prefix 'foo_'
```

--------------------------------

### Start Prometheus Exporter Server

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Start the exporter binary with various configuration options for port, binding, logging, authentication, and labels.

```bash
prometheus_exporter
```

```bash
prometheus_exporter -p 8080 -b 0.0.0.0
```

```bash
prometheus_exporter --verbose --prefix myapp_
```

```bash
prometheus_exporter --histogram
```

```bash
prometheus_exporter --auth /path/to/htpasswd --realm "Metrics"
```

```bash
prometheus_exporter -p 8080 \
                    -b 0.0.0.0 \
                    -t 5 \
                    --prefix 'myapp_' \
                    --label '{"environment": "production", "service": "api"}'
```

--------------------------------

### Start GoodJob Instrumentation

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Place this in your GoodJob initializer file (e.g., config/initializers/good_job.rb) to begin collecting metrics for GoodJob jobs from the database.

```ruby
# e.g. config/initializers/good_job.rb
require 'prometheus_exporter/instrumentation'
PrometheusExporter::Instrumentation::GoodJob.start
```

--------------------------------

### Install Prometheus Exporter Gem

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Add the gem to your application's Gemfile and run bundle install, or install it directly using the gem install command.

```ruby
gem 'prometheus_exporter'
```

```bash
$ bundle

```

```bash
$ gem install prometheus_exporter

```

--------------------------------

### Start Puma Server Instrumentation

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Collects metrics from the Puma web server, including worker and thread pool stats. Start this in your Puma configuration file.

```ruby
# config/puma.rb

# For Puma single mode
require 'prometheus_exporter/instrumentation'
if !PrometheusExporter::Instrumentation::Puma.started?
  PrometheusExporter::Instrumentation::Puma.start(
    frequency: 30,
    labels: { app: 'myapp' }
  )
end
```

```ruby
# For Puma clustered mode
on_worker_boot do
  require 'prometheus_exporter/instrumentation'
  if !PrometheusExporter::Instrumentation::Puma.started?
    PrometheusExporter::Instrumentation::Puma.start(
      frequency: 30,
      labels: { app: 'myapp' }
    )
  end
end
```

```ruby
# Also start process instrumentation
on_worker_boot do
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::Process.start(type: 'puma_worker')
end
```

--------------------------------

### Run Prometheus Exporter

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Start the exporter as a background process. This command assumes the exporter is installed and in your PATH.

```bash
$ prometheus_exporter
```

--------------------------------

### Start Puma Instrumentation

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Include this in your puma.rb configuration to start Prometheus instrumentation for Puma. It ensures threads are not spun up unnecessarily.

```ruby
after_worker_boot do
  require 'prometheus_exporter/instrumentation'
  # optional check, avoids spinning up and down threads per worker
  if !PrometheusExporter::Instrumentation::Puma.started?
    PrometheusExporter::Instrumentation::Puma.start
  end
end
```

--------------------------------

### Start Process Instrumentation

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Collects Ruby process metrics like memory usage and GC stats. Start this in your Rails initializer for the main process and after_fork for worker processes.

```ruby
require 'prometheus_exporter/instrumentation'

# For the main/master process
unless Rails.env.test?
  PrometheusExporter::Instrumentation::Process.start(
    type: "master",
    frequency: 30,  # collect every 30 seconds
    labels: { app: "myapp", environment: Rails.env }
  )
end
```

```ruby
# For forked workers (Unicorn/Puma/Passenger)
after_fork do |server, worker|
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::Process.start(
    type: "web",
    labels: { worker_id: worker.nr }
  )
end
```

--------------------------------

### Install Prometheus Exporter Gem

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Add the gem to your Gemfile or install it directly using the gem command.

```ruby
gem 'prometheus_exporter'
```

```bash
bundle install
```

```bash
gem install prometheus_exporter
```

--------------------------------

### Single Process Mode Setup and Metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Sets up a web server to expose metrics and instruments the process with basic metrics like RSS and Ruby metrics. It also demonstrates creating and observing Gauge, Counter, Summary, and Histogram metrics.

```ruby
require 'prometheus_exporter/server'

# client allows instrumentation to send info to server
require 'prometheus_exporter/client'
require 'prometheus_exporter/instrumentation'

# bind is the address, on which the webserver will listen
# port is the port that will provide the /metrics route
server = PrometheusExporter::Server::WebServer.new bind: 'localhost', port: 12345
server.start

# wire up a default local client
PrometheusExporter::Client.default = PrometheusExporter::LocalClient.new(collector: server.collector)

# this ensures basic process instrumentation metrics are added such as RSS and Ruby metrics
PrometheusExporter::Instrumentation::Process.start(type: "my program", labels: {my_custom: "label for all process metrics"})

gauge = PrometheusExporter::Metric::Gauge.new("rss", "used RSS for process")
counter = PrometheusExporter::Metric::Counter.new("web_requests", "number of web requests")
summary = PrometheusExporter::Metric::Summary.new("page_load_time", "time it took to load page")
histogram = PrometheusExporter::Metric::Histogram.new("api_access_time", "time it took to call api")

server.collector.register_metric(gauge)
server.collector.register_metric(counter)
server.collector.register_metric(summary)
server.collector.register_metric(histogram)

gauge.observe(server.get_rss)
gauge.observe(server.get_rss)

counter.observe(1, route: 'test/route')
counter.observe(1, route: 'another/route')

summary.observe(1.1)
summary.observe(1.12)
summary.observe(0.12)

histogram.observe(0.2, api: 'twitter')

# http://localhost:12345/metrics now returns all your metrics

```

--------------------------------

### Start Process Instrumentation in Rails Initializer

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Include this in an initializer to report basic process statistics like RSS and GC information. Ensure it's not run in the test environment.

```ruby
unless Rails.env.test?
  require 'prometheus_exporter/instrumentation'

  # this reports basic process stats like RSS and GC info
  PrometheusExporter::Instrumentation::Process.start(type: "master")
end
```

--------------------------------

### Start Process Instrumentation After Fork in Web Servers

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

For web servers like Unicorn, Puma, or Passenger, run a new process instrumenter after a fork to collect web-specific process metrics.

```ruby
after_fork do
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::Process.start(type: "web")
end
```

--------------------------------

### Start Resque Instrumentation

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Add this to your Resque initializer file (e.g., config/initializers/resque.rb) to enable Prometheus metrics collection for Resque jobs.

```ruby
# e.g. config/initializers/resque.rb
require 'prometheus_exporter/instrumentation'
PrometheusExporter::Instrumentation::Resque.start
```

--------------------------------

### Enable histogram mode

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Starts the exporter in histogram mode to allow aggregation across labels.

```bash
$ prometheus_exporter --histogram
```

--------------------------------

### Launch Exporter with Custom Collector

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Start the Prometheus exporter process, specifying the path to your custom collector file using the `--collector` argument.

```bash
$ bin/prometheus_exporter --collector examples/custom_collector.rb
```

--------------------------------

### Run Rails Exporter with Bundle

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Start the Prometheus exporter for a Rails application using Bundler. Ensure this runs as a monitored background process.

```bash
$ bundle exec prometheus_exporter
```

--------------------------------

### Define Prometheus Metric with Labels

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Example format for a Prometheus metric with specific labels and a value.

```text
# myapp_requests{hostname="server-1",environment="production",method="GET"} 1
```

--------------------------------

### Instrument Puma in Single Mode

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Start Puma metrics collection in single mode within the puma.rb configuration file.

```ruby
# puma.rb config
require 'prometheus_exporter/instrumentation'
# optional check, avoids spinning up and down threads per worker
if !PrometheusExporter::Instrumentation::Puma.started?
  PrometheusExporter::Instrumentation::Puma.start
end
```

--------------------------------

### Instrument ActiveRecord for Sidekiq

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Start ActiveRecord instrumentation for Sidekiq. Configures custom labels for the 'sidekiq' type.

```ruby
Sidekiq.configure_server do |config|
  config.on :startup do
    require 'prometheus_exporter/instrumentation'
    PrometheusExporter::Instrumentation::ActiveRecord.start(
      custom_labels: { type: "sidekiq" },
      config_labels: [:database]
    )
  end
end
```

--------------------------------

### Start Active Record Instrumentation for Sidekiq

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Enable Active Record connection pool metrics for Sidekiq by requiring the instrumentation and calling PrometheusExporter::Instrumentation::ActiveRecord.start within the Sidekiq server's startup configuration.

```ruby
Sidekiq.configure_server do |config|
  config.on :startup do
    require 'prometheus_exporter/instrumentation'
    PrometheusExporter::Instrumentation::ActiveRecord.start(
      custom_labels: { type: "sidekiq" }, #optional params
      config_labels: [:database, :host] #optional params
    )
  end
end
```

--------------------------------

### Start Active Record Instrumentation for Unicorn/Passenger

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Integrate Active Record connection pool metrics collection for Unicorn or Passenger by calling PrometheusExporter::Instrumentation::ActiveRecord.start within the after_fork hook.

```ruby
after_fork do |_server, _worker|
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::ActiveRecord.start(
    custom_labels: { type: "unicorn_worker" }, #optional params
    config_labels: [:database, :host] #optional params
  )
end
```

--------------------------------

### Configure Shoryuken Server Middleware

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Integrates Prometheus Exporter's Shoryuken instrumentation by adding it to the server middleware chain. Ensure this is configured before Shoryuken starts processing jobs.

```ruby
Shoryuken.configure_server do |config|
  config.server_middleware do |chain|
    require 'prometheus_exporter/instrumentation'
    chain.add PrometheusExporter::Instrumentation::Shoryuken
  end
end
```

--------------------------------

### Run Prometheus Exporter for Unicorn

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Execute the prometheus_exporter command with the necessary flags to monitor Unicorn processes. Ensure the 'raindrops' gem is installed.

```bash
prometheus_exporter --unicorn-master /var/run/unicorn.pid --unicorn-listen-address 127.0.0.1:3000
```

```bash
# alternatively, if you're using unix sockets:
prometheus_exporter --unicorn-master /var/run/unicorn.pid --unicorn-listen-address /var/run/unicorn.sock
```

--------------------------------

### Run Prometheus Exporter Docker Container

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Start the Prometheus Exporter Docker container, exposing port 9394. Additional flags like `--verbose` or `--prefix` can be passed.

```bash
docker run -p 9394:9394 discourse/prometheus_exporter
```

```bash
docker run -p 9394:9394 discourse/prometheus_exporter --verbose --prefix=myapp
```

--------------------------------

### Configure Sidekiq Server for Prometheus Metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Integrates Prometheus Exporter instrumentation into the Sidekiq server. This setup includes middleware for job-specific metrics, a death handler, and startup tasks for process and queue statistics.

```ruby
Sidekiq.configure_server do |config|
  require 'prometheus_exporter/instrumentation'
  config.server_middleware do |chain|
    chain.add PrometheusExporter::Instrumentation::Sidekiq
  end
  config.death_handlers << PrometheusExporter::Instrumentation::Sidekiq.death_handler
  config.on :startup do
    PrometheusExporter::Instrumentation::Process.start type: 'sidekiq'
    PrometheusExporter::Instrumentation::SidekiqProcess.start
    PrometheusExporter::Instrumentation::SidekiqQueue.start
    PrometheusExporter::Instrumentation::SidekiqStats.start
  end
end
```

--------------------------------

### Start Active Record Instrumentation for Puma Single Mode

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Use PrometheusExporter::Instrumentation::ActiveRecord.start in puma.rb to collect Active Record connection pool metrics. Supports custom labels and configuration labels.

```ruby
#in puma.rb
require 'prometheus_exporter/instrumentation'
PrometheusExporter::Instrumentation::ActiveRecord.start(
  custom_labels: { type: "puma_single_mode" }, #optional params
  config_labels: [:database, :host] #optional params
)
```

--------------------------------

### Start Active Record Instrumentation for Puma Cluster Mode

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Configure Active Record instrumentation for Puma cluster mode by calling PrometheusExporter::Instrumentation::ActiveRecord.start within the on_worker_boot block in puma.rb.

```ruby
# in puma.rb
on_worker_boot do
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::ActiveRecord.start(
    custom_labels: { type: "puma_worker" }, #optional params
    config_labels: [:database, :host] #optional params
  )
end
```

--------------------------------

### Instrument ActiveRecord for Puma Clustered Mode

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Start ActiveRecord instrumentation for Puma clustered mode workers. Includes database host and port as labels.

```ruby
require 'prometheus_exporter/instrumentation'
PrometheusExporter::Instrumentation::ActiveRecord.start(
  custom_labels: { type: "puma_worker" },
  config_labels: [:database, :host, :port]
)
```

--------------------------------

### Instrument ActiveRecord for Puma Single Mode

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Start ActiveRecord instrumentation for Puma single mode. Sets frequency and includes specific configuration labels.

```ruby
require 'prometheus_exporter/instrumentation'
PrometheusExporter::Instrumentation::ActiveRecord.start(
  frequency: 30,
  custom_labels: { type: "puma_single" },
  config_labels: [:database, :host]  # Include DB config as labels
)
```

--------------------------------

### Configure WebServer for Metrics

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Initializes the WebServer to collect and expose metrics, including local client registration and process instrumentation.

```ruby
require 'prometheus_exporter/server'
require 'prometheus_exporter/client'
require 'prometheus_exporter/instrumentation'

# Start a metrics server in single process mode
server = PrometheusExporter::Server::WebServer.new(
  port: 9394,
  bind: 'localhost',
  timeout: 5,
  verbose: true
)
server.start

# Wire up a local client that sends directly to the collector
PrometheusExporter::Client.default = PrometheusExporter::LocalClient.new(
  collector: server.collector
)

# Register and use metrics directly with the collector
gauge = PrometheusExporter::Metric::Gauge.new("app_version", "Application version info")
gauge.observe(1, version: "2.3.1", commit: "abc123")
server.collector.register_metric(gauge)

counter = PrometheusExporter::Metric::Counter.new("events_total", "Total events processed")
server.collector.register_metric(counter)
counter.observe(1, type: "user_signup")

# Start process instrumentation
PrometheusExporter::Instrumentation::Process.start(type: "main")

# Metrics available at http://localhost:9394/metrics
# Health check at http://localhost:9394/ping (returns "PONG")

# Graceful shutdown
at_exit { server.stop }
```

--------------------------------

### Implement Summary Metrics

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Calculates quantiles over a sliding window for percentile tracking.

```ruby
require 'prometheus_exporter/metric'

# Default quantiles: [0.99, 0.9, 0.5, 0.1, 0.01]
summary = PrometheusExporter::Metric::Summary.new(
  "http_request_duration_seconds",
  "HTTP request latency",
  quantiles: [0.5, 0.9, 0.95, 0.99]
)

# Observe multiple values
[0.012, 0.045, 0.089, 0.123, 0.234, 0.456, 0.789, 1.234].each do |duration|
  summary.observe(duration, handler: "api")
end

# Get data
summary.to_h
# => {{handler: "api"} => {"count" => 8, "sum" => 2.982}}

puts summary.to_prometheus_text
# HELP http_request_duration_seconds HTTP request latency
# TYPE http_request_duration_seconds summary
# http_request_duration_seconds{handler="api",quantile="0.5"} 0.234
# http_request_duration_seconds{handler="api",quantile="0.9"} 0.789
# http_request_duration_seconds{handler="api",quantile="0.95"} 1.234
# http_request_duration_seconds{handler="api",quantile="0.99"} 1.234
# http_request_duration_seconds_sum{handler="api"} 2.982
# http_request_duration_seconds_count{handler="api"} 8
```

--------------------------------

### Initialize Prometheus Client with Custom Labels

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Configure the Prometheus client with global custom labels to be applied to all metrics.

```ruby
client = PrometheusExporter::Client.new(
  custom_labels: { service: "api", version: "2.0" }
)
```

--------------------------------

### Enable basic authentication for metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Commands to enable authentication on the metrics route and generate a password file.

```bash
$ prometheus_exporter --auth my-htpasswd-file
```

```bash
$ htpasswd -cdb my-htpasswd-file my-user my-unencrypted-password
```

--------------------------------

### Configure exporter process via CLI

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Lists available command-line options for the prometheus_exporter binary.

```bash
Usage: prometheus_exporter [options]
    -p, --port INTEGER               Port exporter should listen on (default: 9394)
    -b, --bind STRING                IP address exporter should listen on (default: localhost)
    -t, --timeout INTEGER            Timeout in seconds for metrics endpoint (default: 2)
        --prefix METRIC_PREFIX       Prefix to apply to all metrics (default: ruby_)
        --label METRIC_LABEL         Label to apply to all metrics (default: {})
    -c, --collector FILE             (optional) Custom collector to run
    -a, --type-collector FILE        (optional) Custom type collectors to run in main collector
    -v, --verbose
    -g, --histogram                  Use histogram instead of summary for aggregations
        --auth FILE                  (optional) enable basic authentication using a htpasswd FILE
        --realm REALM                (optional) Use REALM for basic authentication (default: "Prometheus Exporter")
        --unicorn-listen-address ADDRESS
                                     (optional) Address where unicorn listens on (unix or TCP address)
        --unicorn-master PID_FILE    (optional) PID file of unicorn master process to monitor unicorn
```

--------------------------------

### Create and Observe a Counter Metric with Defaults

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Create a counter metric and observe its value. The metric will automatically include the default prefix and labels configured globally.

```ruby
require 'prometheus_exporter/metric'

# Set default prefix for all metric names
PrometheusExporter::Metric::Base.default_prefix = "myapp_"

# Set default labels added to all metrics
PrometheusExporter::Metric::Base.default_labels = {
  hostname: Socket.gethostname,
  environment: ENV['RAILS_ENV'] || 'development'
}

# Create metrics - they inherit defaults
counter = PrometheusExporter::Metric::Counter.new("requests", "HTTP requests")
counter.observe(1, method: "GET")

puts counter.to_prometheus_text
```

--------------------------------

### Configure client-side default labels

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Sets custom labels during client initialization or on an existing client instance.

```ruby
# Specify on intializing PrometheusExporter::Client
PrometheusExporter::Client.new(custom_labels: { hostname: 'app-server-01', app_name: 'app-01' })

# Specify on an instance of PrometheusExporter::Client
client = PrometheusExporter::Client.new
client.custom_labels = { hostname: 'app-server-01', app_name: 'app-01' }
```

--------------------------------

### Load Custom Collector via Command Line

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

To use a custom collector file, specify its path using the `-a` flag when running the `prometheus_exporter` command.

```bash
$ bundle exec prometheus_exporter -a person_collector.rb
```

--------------------------------

### Custom Quantiles and Buckets for Metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Allows customization of quantiles for Summary metrics and buckets for Histogram metrics to better suit specific measurement needs.

```ruby
summary = PrometheusExporter::Metric::Summary.new("load_time", "time to load page", quantiles: [0.99, 0.75, 0.5, 0.25])
histogram = PrometheusExporter::Metric::Histogram.new("api_time", "time to call api", buckets: [0.1, 0.5, 1])

```

--------------------------------

### Expose Sidekiq Metrics via Rake Task

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Sets up a standalone process using a rake task to expose Sidekiq metrics. This is an alternative to server-side integration, suitable for long-lived processes. Ensure `all_queues: true` is used if metrics for all queues are needed.

```ruby
task :sidekiq_metrics do
  server = PrometheusExporter::Server::WebServer.new
  server.start

  PrometheusExporter::Client.default = PrometheusExporter::LocalClient.new(collector: server.collector)

  PrometheusExporter::Instrumentation::SidekiqQueue.start(all_queues: true)
  PrometheusExporter::Instrumentation::SidekiqStats.start
  sleep
end
```

--------------------------------

### Define default labels and counter metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Sets global default labels and demonstrates incrementing a counter metric.

```ruby
PrometheusExporter::Metric::Base.default_labels = { "hostname" => "app-server-01" }

counter = PrometheusExporter::Metric::Counter.new("web_requests", "number of web requests")

counter.observe(1, route: 'test/route')
counter.observe
```

--------------------------------

### Configure Middleware to Use Prepend

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Optionally configure the Prometheus Exporter middleware to use the 'prepend' method for instrumentation instead of the default 'alias_method'. This can resolve conflicts with other instrumentation libraries.

```ruby
Rails.application.middleware.unshift PrometheusExporter::Middleware, instrument: :prepend
```

--------------------------------

### Implement Histogram Metrics

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Configures custom buckets for latency tracking and observes values to generate distribution data.

```ruby
require 'prometheus_exporter/metric'

# Default buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5.0, 10.0]
histogram = PrometheusExporter::Metric::Histogram.new(
  "http_request_duration_seconds",
  "HTTP request latency in seconds",
  buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0]
)

# Observe values
histogram.observe(0.032, endpoint: "/api/users")
histogram.observe(0.156, endpoint: "/api/users")
histogram.observe(0.891, endpoint: "/api/users")
histogram.observe(2.341, endpoint: "/api/orders")

# Set global default buckets
PrometheusExporter::Metric::Histogram.default_buckets = [0.1, 0.5, 1, 2, 5, 10, 30, 60]

# Get data
histogram.to_h
# => {{endpoint: "/api/users"} => {"count" => 3, "sum" => 1.079}, ...}

puts histogram.to_prometheus_text
# HELP http_request_duration_seconds HTTP request latency in seconds
# TYPE http_request_duration_seconds histogram
# http_request_duration_seconds_bucket{endpoint="/api/users",le="0.01"} 0
# http_request_duration_seconds_bucket{endpoint="/api/users",le="0.05"} 1
# http_request_duration_seconds_bucket{endpoint="/api/users",le="0.1"} 1
# http_request_duration_seconds_bucket{endpoint="/api/users",le="0.25"} 2
# ...
# http_request_duration_seconds_bucket{endpoint="/api/users",le="+Inf"} 3
# http_request_duration_seconds_count{endpoint="/api/users"} 3
# http_request_duration_seconds_sum{endpoint="/api/users"} 1.079
```

--------------------------------

### Configure Default Histogram Buckets

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Set the default buckets for histogram metrics globally. This allows for consistent distribution aggregation across different histograms.

```ruby
require 'prometheus_exporter/metric'

# Set default histogram buckets globally
PrometheusExporter::Metric::Histogram.default_buckets = [
  0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10
]
```

--------------------------------

### Configure Default Metric Prefix

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Set a default prefix for all metric names globally. This simplifies metric naming conventions across the application.

```ruby
require 'prometheus_exporter/metric'

# Set default prefix for all metric names
PrometheusExporter::Metric::Base.default_prefix = "myapp_"
```

--------------------------------

### Observe Gauge Metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Register and observe values for a gauge metric. This client code should be run within your application.

```ruby
require 'prometheus_exporter/client'

client = PrometheusExporter::Client.default
gauge = client.register(:gauge, "awesome", "amount of awesome")

gauge.observe(10)
gauge.observe(99, day: "friday")
```

--------------------------------

### Manage Gauge Metrics

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Demonstrates removing label sets and tracking active jobs using the Gauge metric type.

```ruby
gauge.observe(nil, instance: "worker-1")  # Removes the metric
gauge.remove(instance: "worker-2")         # Alternative removal

# Track active jobs
active_jobs = PrometheusExporter::Metric::Gauge.new("active_jobs", "Currently processing jobs")
active_jobs.increment({ queue: "default" })
# ... job processing ...
active_jobs.decrement({ queue: "default" })

puts gauge.to_prometheus_text
# HELP memory_usage_bytes Current memory usage
# TYPE memory_usage_bytes gauge
# memory_usage_bytes 576716800
```

--------------------------------

### Configure Default Metric Labels

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Set default labels that are automatically appended to all metrics. This is useful for adding common context like hostname and environment.

```ruby
require 'prometheus_exporter/metric'

# Set default labels added to all metrics
PrometheusExporter::Metric::Base.default_labels = {
  hostname: Socket.gethostname,
  environment: ENV['RAILS_ENV'] || 'development'
}
```

--------------------------------

### PrometheusExporter::Client Usage

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Use the Client class to send metrics to the exporter server. Configure custom clients with options like host, port, queue size, and labels. Register and observe various metric types.

```ruby
require 'prometheus_exporter/client'

# Use the default client (connects to localhost:9394)
client = PrometheusExporter::Client.default

# Create a custom client with options
client = PrometheusExporter::Client.new(
  host: 'metrics-server.example.com',
  port: 9394,
  max_queue_size: 10_000,
  thread_sleep: 0.5,
  custom_labels: { service: 'my-app', environment: 'production' },
  logger: Rails.logger,
  log_level: Logger::INFO
)

# Set as the default client
PrometheusExporter::Client.default = client

# Register and use metrics
counter = client.register(:counter, "requests_total", "Total HTTP requests")
counter.observe(1)
counter.observe(1, status: "200", method: "GET")

gauge = client.register(:gauge, "active_connections", "Active DB connections")
gauge.observe(42)
gauge.increment(method: "POST")
gauge.decrement(method: "POST")

histogram = client.register(:histogram, "request_duration_seconds", "Request latency", buckets: [0.1, 0.5, 1, 2.5, 5])
histogram.observe(0.234, endpoint: "/api/users")

summary = client.register(:summary, "response_size_bytes", "Response size", quantiles: [0.5, 0.9, 0.99])
summary.observe(1024, route: "home")

# Stop client gracefully (useful before process exit)
client.stop(wait_timeout_seconds: 10)
```

--------------------------------

### Define a Custom Collector for Multi-Process Mode

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Implement a custom collector by inheriting from `PrometheusExporter::Server::CollectorBase`. You must provide implementations for the `#process` and `#prometheus_metrics_text` methods.

```ruby
class MyCustomCollector < PrometheusExporter::Server::CollectorBase
  def initialize
    @gauge1 = PrometheusExporter::Metric::Gauge.new("thing1", "I am thing 1")
    @gauge2 = PrometheusExporter::Metric::Gauge.new("thing2", "I am thing 2")
    @mutex = Mutex.new
  end

  def process(str)
    obj = JSON.parse(str)
    @mutex.synchronize do
      if thing1 = obj["thing1"]
        @gauge1.observe(thing1)
      end

      if thing2 = obj["thing2"]
        @gauge2.observe(thing2)
      end
    end
  end

  def prometheus_metrics_text
    @mutex.synchronize do
      "#{@gauge1.to_prometheus_text}\n#{@gauge2.to_prometheus_text}"
    end
  end
end
```

--------------------------------

### Register Histogram Metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Register a histogram metric with custom buckets and observe values. This allows for detailed performance analysis.

```ruby
require 'prometheus_exporter/client'

client = PrometheusExporter::Client.default
histogram = client.register(:histogram, "api_time", "time to call api", buckets: [0.1, 0.5, 1])

histogram.observe(0.2, api: 'twitter')
```

--------------------------------

### Define Custom Labels for Sidekiq Job Metrics

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Allows adding custom labels to Sidekiq metrics for individual jobs. Define a `custom_labels` class method on the job class to return a hash of key-value pairs that will be appended to the metrics.

```ruby
class WorkerWithCustomLabels
  def self.custom_labels
    { my_label: 'value-here', other_label: 'second-val' }
  end

  def perform; end
end
```

--------------------------------

### View Metrics from Custom Collector

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Access the `/metrics` endpoint of the running exporter to view the collected metrics. The output will include both default and custom metrics.

```bash
$ curl localhost:12345/metrics
# HELP collector_working Is the master process collector able to collect metrics
# TYPE collector_working gauge
collector_working 1

# HELP thing1 I am thing 1
# TYPE thing1 gauge
thing1 122

# HELP thing2 I am thing 2
# TYPE thing2 gauge
thing2 12
```

--------------------------------

### Define a Custom User Metrics Collector

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Create a custom type collector for user-related metrics like signups and active users. Metrics are defined with specific labels.

```ruby
class UserCollector < PrometheusExporter::Server::TypeCollector
  def initialize
    @user_signups = PrometheusExporter::Metric::Counter.new(
      "user_signups_total",
      "Total user signups"
    )
    @active_users = PrometheusExporter::Metric::Gauge.new(
      "active_users",
      "Currently active users"
    )
  end

  def type
    "user_stats"
  end

  def collect(obj)
    labels = { plan: obj["plan"] || "free" }

    if obj["signup"]
      @user_signups.observe(1, labels)
    end

    if obj["active_count"]
      @active_users.observe(obj["active_count"], labels)
    end
  end

  def metrics
    [@user_signups, @active_users]
  end
end
```

--------------------------------

### Send Metrics to Custom Collector

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Instantiate a `PrometheusExporter::Client` and use its `send_json` method to send metric data to the exporter. Ensure the host and port match your exporter's configuration.

```ruby
require 'prometheus_exporter/client'

client = PrometheusExporter::Client.new(host: 'localhost', port: 12345)
client.send_json(thing1: 122)
client.send_json(thing2: 12)
```

--------------------------------

### Fetch Metrics from Exporter

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Retrieve collected metrics by curling the exporter's endpoint. This is useful for verifying that metrics are being exposed correctly.

```bash
$ curl localhost:9394/metrics
# HELP collector_working Is the master process collector able to collect metrics
# TYPE collector_working gauge
collector_working 1

# HELP awesome amount of awesome
# TYPE awesome gauge
awesome{day="friday"} 99
awesome 10
```

--------------------------------

### Specify Histogram Buckets on Instance

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Define custom buckets for a specific histogram instance by passing the `buckets` option during initialization. Instance-specific buckets take precedence over default buckets.

```ruby
Histogram.default_buckets = [0.005, 0.01, 0,5].freeze
buckets = [0.1, 0.2, 0.3]
histogram = Histogram.new('test_bucktets', 'I have specified buckets', buckets: buckets)
histogram.buckets => [0.1, 0.2, 0.3]
```

--------------------------------

### Configure Prometheus Exporter Client Log Level

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Set the logging verbosity for `PrometheusExporter::Client` by passing a `log_level` argument. The default level is `Logger::WARN`.

```ruby
PrometheusExporter::Client.new(log_level: Logger::DEBUG)
```

--------------------------------

### Instrument Sidekiq Jobs

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Integrates Prometheus Exporter with Sidekiq to monitor job execution, queue status, and process metrics. Configure this in your Sidekiq initializer.

```ruby
# config/initializers/sidekiq.rb
Sidekiq.configure_server do |config|
  require 'prometheus_exporter/instrumentation'

  # Add middleware for job metrics
  config.server_middleware do |chain|
    chain.add PrometheusExporter::Instrumentation::Sidekiq
  end

  # Track dead jobs
  config.death_handlers << PrometheusExporter::Instrumentation::Sidekiq.death_handler

  config.on :startup do
    # Process metrics (memory, GC)
    PrometheusExporter::Instrumentation::Process.start(type: 'sidekiq')

    # Sidekiq process metrics (concurrency, busy workers)
    PrometheusExporter::Instrumentation::SidekiqProcess.start

    # Queue metrics (backlog, latency)
    PrometheusExporter::Instrumentation::SidekiqQueue.start

    # Global Sidekiq stats
    PrometheusExporter::Instrumentation::SidekiqStats.start
  end
end
```

```ruby
# Ensure metrics are sent before shutdown
Sidekiq.configure_server do |config|
  at_exit do
    PrometheusExporter::Client.default.stop(wait_timeout_seconds: 10)
  end
end
```

```ruby
# Add custom labels to specific workers
class MyWorker
  include Sidekiq::Worker

  def self.custom_labels
    { priority: 'high', team: 'payments' }
  end

  def perform(user_id)
    # job logic
  end
end
```

--------------------------------

### Register Delayed Job Instrumentation Plugin

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Register the Prometheus Exporter plugin for Delayed Job. This should be done in an initializer and excludes the test environment.

```ruby
unless Rails.env.test?
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::DelayedJob.register_plugin(
    client: PrometheusExporter::Client.default,
    include_module_name: true  # Include full class name with module
  )
end
```

--------------------------------

### Configure Prometheus Exporter Client Logger

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Instantiate `PrometheusExporter::Client` with a custom logger object, such as `Rails.logger` or a new `Logger` instance. The default logger exports to STDERR.

```ruby
PrometheusExporter::Client.new(logger: Rails.logger)
```

```ruby
PrometheusExporter::Client.new(logger: Logger.new(STDOUT))
```

--------------------------------

### Instrument Hutch Message Processing

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Configure the Hutch tracer to capture job metrics. Ensure this is not executed in the test environment.

```ruby
unless Rails.env.test?
  require 'prometheus_exporter/instrumentation'
  Hutch::Config.set(:tracer, PrometheusExporter::Instrumentation::Hutch)
end
```

--------------------------------

### Gracefully Stop Prometheus Exporter Client on Sidekiq Shutdown

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Ensures that metrics generated just before Sidekiq shuts down are sent to the collector. This is particularly important for metrics like `sidekiq_restarted_jobs_total`. The client is explicitly stopped with a specified wait timeout.

```ruby
Sidekiq.configure_server do |config|
  at_exit do
    PrometheusExporter::Client.default.stop(wait_timeout_seconds: 10)
  end
end
```

--------------------------------

### Kubernetes Healthcheck Configuration

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Configure a Kubernetes healthcheck for the Prometheus Exporter service using a `CMD` test that pings the `/ping` endpoint. Adjust timeout, interval, and retries as needed.

```yaml
services:
  rails-exporter:
    command:
      - bin/prometheus_exporter
      - -b
      - 0.0.0.0
    healthcheck:
      test: ["CMD", "curl", "--silent", "--show-error", "--fail", "--max-time", "3", "http://0.0.0.0:9394/ping"]
      timeout: 3s
      interval: 10s
      retries: 5
```

--------------------------------

### Collect Global User Count Metric

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Define a `Gauge` metric within the `metrics` method of a custom type collector to track global application metrics like user count. Consider using caching for frequently accessed data.

```ruby
def metrics
  user_count_gauge = PrometheusExporter::Metric::Gauge.new('user_count', 'number of users in the app')
  user_count_gauge.observe User.count
  [user_count_gauge]
end
```

--------------------------------

### Set Default Histogram Buckets

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Customize the default buckets used for histograms by assigning an array of floats to `Histogram.default_buckets`. Ensure the array is frozen for immutability.

```ruby
[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5.0, 10.0].freeze
```

```ruby
Histogram.default_buckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 2.5, 3, 4, 5.0, 10.0, 12, 14, 15, 20, 25].freeze
```

--------------------------------

### Pull Prometheus Exporter Docker Image

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Download the latest official Docker image for Prometheus Exporter using `docker pull`. You can also specify a version tag.

```bash
docker pull discourse/prometheus_exporter:latest
```

```bash
# or use specific version
docker pull discourse/prometheus_exporter:x.x.x
```

--------------------------------

### Add Custom Labels to Prometheus Middleware

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Extend PrometheusExporter::Middleware and override custom_labels to add your own labels based on the request environment.

```ruby
class MyMiddleware < PrometheusExporter::Middleware
  def custom_labels(env)
    labels = {}

    if env['HTTP_X_PLATFORM']
      labels['platform'] = env['HTTP_X_PLATFORM']
    end

    labels
  end
end
```

--------------------------------

### Integrate Prometheus Exporter Middleware

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Add the Prometheus Exporter middleware to your Rails application's stack in an initializer. This middleware tracks request metrics.

```ruby
unless Rails.env.test?
  require 'prometheus_exporter/middleware'

  # This reports stats per request like HTTP status and timings
  Rails.application.middleware.unshift PrometheusExporter::Middleware
end
```

--------------------------------

### Send Custom User Metrics

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Send custom user metrics to the Prometheus Exporter client. Metrics are sent as JSON objects with a specified type and relevant data.

```ruby
client = PrometheusExporter::Client.default
client.send_json(type: "user_stats", signup: true, plan: "premium")
client.send_json(type: "user_stats", active_count: 1523, plan: "free")
client.send_json(type: "user_stats", active_count: 892, plan: "premium")
```

--------------------------------

### Send Custom Person Metric

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Use the default client to send custom metric data in JSON format. The `type` field should match the `type` method in your custom collector.

```ruby
PrometheusExporter::Client.default.send_json(type: "person", age: 40)
```

--------------------------------

### Register Delayed Job Plugin

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Registers the PrometheusExporter::Instrumentation::DelayedJob plugin in a Rails initializer. This should be done outside of the test environment to avoid unnecessary overhead.

```ruby
unless Rails.env.test?
  require 'prometheus_exporter/instrumentation'
  PrometheusExporter::Instrumentation::DelayedJob.register_plugin
end
```

--------------------------------

### Ensure Rails Environment in Custom Collector

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

When collecting global metrics within a custom type collector, ensure the Rails environment is loaded if it's not already defined. This provides access to Rails models and functionalities.

```ruby
unless defined? Rails
  require File.expand_path("../../config/environment", __FILE__)
end
```

--------------------------------

### Custom Prometheus Middleware with Labels

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Subclass PrometheusExporter::Middleware to add custom labels based on request headers. This allows for more granular metric filtering and grouping.

```ruby
class CustomPrometheusMiddleware < PrometheusExporter::Middleware
  def custom_labels(env)
    labels = {}
    labels['tenant'] = env['HTTP_X_TENANT_ID'] if env['HTTP_X_TENANT_ID']
    labels['api_version'] = env['HTTP_X_API_VERSION'] if env['HTTP_X_API_VERSION']
    labels
  end
end

Rails.application.middleware.unshift CustomPrometheusMiddleware
```

--------------------------------

### Set Default Metric Prefix

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

In single-process mode, you can set a default prefix for all metric names by assigning a string to `PrometheusExporter::Metric::Base.default_prefix`.

```ruby
# Specify prefix for metric names
PrometheusExporter::Metric::Base.default_prefix = "ruby"
```

--------------------------------

### Customize Default Labels for Non-Rails Frameworks

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Override default_labels in PrometheusExporter::Middleware to mimic prometheus-client labels for frameworks other than Rails. This allows for more detailed metrics like path, method, and status.

```ruby
class MyMiddleware < PrometheusExporter::Middleware
  def default_labels(env, result)
    status = (result && result[0]) || -1
    path = [env["SCRIPT_NAME"], env["PATH_INFO"]].join
    {
      path: strip_ids_from_path(path),
      method: env["REQUEST_METHOD"],
      status: status
    }
  end

  def strip_ids_from_path(path)
    path
      .gsub(%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(/|$)}, '/:uuid\1')
      .gsub(%r{/\d+(/|$)}, '/:id\1')
  end
end
```

--------------------------------

### Add Prometheus Exporter Middleware to Rails

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

Integrates the Prometheus Exporter middleware into a Rails application to track HTTP requests. Ensure this is not run in the test environment.

```ruby
unless Rails.env.test?
  require 'prometheus_exporter/middleware'

  # Add middleware to track HTTP requests
  Rails.application.middleware.unshift PrometheusExporter::Middleware

  # Or with prepend instrumentation (for compatibility with other profiling gems)
  Rails.application.middleware.unshift PrometheusExporter::Middleware, instrument: :prepend
end
```

--------------------------------

### Add Prometheus Exporter to Gemfile

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Include the prometheus_exporter gem in your Rails application's Gemfile to enable its features.

```ruby
gem 'prometheus_exporter'
```

--------------------------------

### Define a Custom Person Collector

Source: https://github.com/discourse/prometheus_exporter/blob/main/README.md

Implement a custom type collector by inheriting from `PrometheusExporter::Server::TypeCollector`. This allows you to define specific metrics and how they are collected based on incoming objects.

```ruby
class PersonCollector < PrometheusExporter::Server::TypeCollector
  def initialize
    @oldies = PrometheusExporter::Metric::Counter.new("oldies", "old people")
    @youngies = PrometheusExporter::Metric::Counter.new("youngies", "young people")
  end

  def type
    "person"
  end

  def collect(obj)
    if obj["age"] > 21
      @oldies.observe(1)
    else
      @youngies.observe(1)
    end
  end

  def metrics
    [@oldies, @youngies]
  end
end
```

--------------------------------

### PrometheusExporter::Metric::Counter

Source: https://context7.com/discourse/prometheus_exporter/llms.txt

A cumulative metric that only increases. Use for counting events like requests or tasks. Supports basic increments, labeled increments, and resetting specific label combinations.

```ruby
require 'prometheus_exporter/metric'

counter = PrometheusExporter::Metric::Counter.new("http_requests_total", "Total HTTP requests processed")

# Basic increment
counter.observe(1)

# Increment with labels
counter.observe(1, status: "200", method: "GET")
counter.observe(1, status: "404", method: "GET")
counter.observe(1, status: "500", method: "POST")

# Alternative increment/decrement methods
counter.increment({ endpoint: "/api" }, 5)  # Add 5
counter.decrement({ endpoint: "/api" }, 2)  # Subtract 2

# Reset specific label combination
counter.reset({ status: "500", method: "POST" }, 0)

# Get current data
counter.to_h
# => {{status: "200", method: "GET"} => 1, {status: "404", method: "GET"} => 1, ...}

# Generate Prometheus text format
puts counter.to_prometheus_text
# HELP http_requests_total Total HTTP requests processed
# TYPE http_requests_total counter
# http_requests_total{status="200",method="GET"} 1
# http_requests_total{status="404",method="GET"} 1
```