#
Prometheus Client for Crystal

A Prometheus client library for Crystal following the official guidelines.

##
Installation

1. Add the dependency to your `shard.yml`:

    dependencies:
      prometheus:
        github: pfeifferj/prometheus
        version: ~> 0.1.0

2. Run `shards install`

##
Usage

    require "prometheus"

    # Create metrics
    counter = Prometheus.counter("http_requests_total", "Total HTTP requests")
    gauge = Prometheus.gauge("cpu_usage", "CPU usage percentage")
    histogram = Prometheus.histogram("response_time", "Response time in seconds", [0.1, 0.5, 1.0])
    summary = Prometheus.summary("request_size", "Request size in bytes")

    # Add labels
    labels = Prometheus::LabelSet.new({
      "method" => "GET",
      "handler" => "home"
    })
    requests = Prometheus.counter("http_requests_total", "Total HTTP requests", labels)

    # Use metrics
    counter.inc                 # Increment by 1
    counter.inc(5)              # Increment by given value
    gauge.set(45.2)             # Set to a value
    gauge.inc(5)                # Increase by 5
    gauge.dec(3)                # Decrease by 3
    histogram.observe(0.25)     # Observe a value
    summary.observe(1024)       # Observe a value

    # Get metrics in Prometheus text format
    puts Prometheus.collect

##
Metric Types

###
Counter

A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero.

    counter = Prometheus.counter("http_requests_total", "Total HTTP requests")
    counter.inc      # Increment by 1
    counter.inc(5)   # Increment by 5

###
Gauge

A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.

    gauge = Prometheus.gauge("cpu_usage", "CPU usage percentage")
    gauge.set(45.2)  # Set to 45.2
    gauge.inc(5)     # Increase by 5
    gauge.dec(3)     # Decrease by 3

###
Histogram

A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets.

    # Create with custom buckets
    histogram = Prometheus.histogram(
      "response_time",
      "Response time in seconds",
      [0.1, 0.5, 1.0, 2.0, 5.0]
    )

    # Observe values
    histogram.observe(0.25)

###
Summary

A summary captures individual observations from an event or sample stream and summarizes them in a traditional way, with count and sum.

    summary = Prometheus.summary("request_size", "Request size in bytes")
    summary.observe(1024)

##
Labels

Labels enable Prometheus's dimensional data model. A label set can be attached to any metric:

    # Create a label set
    labels = Prometheus::LabelSet.new({
      "method" => "GET",
      "path" => "/api/users"
    })

    # Create metric with labels
    requests = Prometheus.counter("http_requests_total", "Total HTTP requests", labels)
    requests.inc

    # Output will include labels:
    # http_requests_total{method="GET",path="/api/users"} 1

##
Registry

The library maintains a default registry that manages all metrics. You can access it directly if needed:

    # Register a metric manually
    Prometheus.register(metric)

    # Unregister a metric
    Prometheus.unregister("metric_name")

    # Clear all metrics
    Prometheus.clear

    # Get all metrics in Prometheus text format
    output = Prometheus.collect

##
Thread Safety

All metric operations are thread-safe. The library uses mutexes to ensure proper synchronization in concurrent environments.

##
Development

Run tests:

    crystal spec

##
Contributing

1. Fork it (https://github.com/pfeifferj/prometheus/fork)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request

##
License

This project is licensed under the MIT License - see the LICENSE file for details.