Client-Side Prometheus Metrics API

Introduction

The Client-Side Prometheus Metrics API is a powerful and flexible microservice designed for efficient client-side metrics collection. Built using Golang and the gin framework, this API leverages the gin-metrics package to seamlessly capture and handle a variety of metric types including counters, gauges, histograms, and summaries. Ideal for applications requiring real-time monitoring and performance analysis, this API facilitates easy metrics reporting from HTTP clients.

Installation and Setup

Before installing the client-metrics-api, ensure you have Golang installed on your system. Follow these steps to set up the service:

Clone the Repository: git clone https://github.com/ShragaUser/client-metrics-api Navigate to the Directory: cd client-metrics-api Install Dependencies: go mod download Build the Service: make build`` **Run the Service**: ./client-metrics`

ClientMetrics Package

The clientmetrics package plays a crucial role in handling metric requests. It provides functionalities to process and record different types of metrics such as counters, gauges, histograms, and summaries.

Handling Different Metric Types

Based on the metric type specified in the request (counter, gauge, summary, histogram), the clientmetrics package processes the metric accordingly:

• Counters and Gauges: Incremented by the provided value (default increment is 1).
• Summaries and Histograms: Observations are recorded based on the provided value.

Request Body Format

Clients must send metric data in the following format:

type ClientMetricsRequestBody struct {
    MetricName   string   `json:"metricName"`
    MetricType   string   `json:"metricType"`
    MetricValue  *float64 `json:"metricValue,omitempty"`
    MetricLabels []string `json:"metricLabels,omitempty"`
}

Configuration

The API uses the Config struct to manage configuration settings. These settings are loaded using the Viper library and can be specified in a configuration file or environment variables.

The following settings are available:

Port: The port on which the API service will run. Default is 9091. AllowedOrigins: CORS settings for the API. By default, all origins are allowed ("*"). ManualConfigurationFilePath: Path to the manual configuration file for defining custom metrics. LogLevel: Determines the level of logging. Default is INFO. To customize these settings, you can set them in a configuration file or as environment variables. For example, to change the port and log level, you can set PORT and LOG_LEVEL in your environment.

Configuration File Parsing

The API uses the Config package to parse the configuration file specified in ManualConfigurationFilePath. This file is essential for pre-defining custom metrics like histograms and summaries. The API can dynamically handle counters and gauges without pre-configuration.

The GetPreDefinedCustomMetricsConfig method in the Config struct is used to load and parse this file. If the ManualConfigurationFilePath is not set, this functionality will not be available.

Example configuration file:

metrics:
  - name: histogram_example
    type: histogram
    description: An example of a histogram metric
    buckets: [0.1, 0.2, 0.5, 1.0, 2.5, 5.0, 10.0]
  - name: summary_example
    type: summary
    description: An example of a summary metric
    buckets: [0.1, 0.2, 0.5, 1.0, 2.5, 5.0, 10.0]
  # Add more metrics as needed

Usage Examples

Here are some examples of how to use the API to send different types of metrics:

Posting a Counter Metric

axios.post('/api/v1/metrics', {
  metricName: 'sample_counter',
  metricType: 'counter',
  metricValue: 1
});

Posting a Summary Metric

axios.post('/api/v1/metrics', {
  metricName: 'sample_summary',
  metricType: 'summary',
  metricValue: 150 // in milliseconds
});

API Reference

The API supports various endpoints for different metric types. Each endpoint accepts specific parameters as detailed below:

1. POST /api/v1/metrics: Accepts JSON payload to record a new metric.

2. GET /metrics: This endpoint exposes the collected metrics in a format that Prometheus can scrape. It allows Prometheus to automatically collect and store metrics data, enabling easy integration with Prometheus monitoring tools.

Error Handling

The API provides descriptive error messages in case of invalid requests or internal errors. Example of an error response:

{
  "error": "Invalid metric type provided"
}

Logging

The API uses the slog package for logging. The log level can be configured through the LogLevel setting in the configuration. This allows for flexible control over the amount of log output generated by the service.

Contributing

We welcome contributions to the client-metrics-api project. Please refer to the CONTRIBUTING.md file for contribution guidelines.

License

This project is licensed under the MIT License.