PromEx

https://prom-ex.hexdocs.pm/
Admin
PromEx is a library that provides Prometheus metrics and Grafana dashboards for Elixir applications,...
Tokens:27,564
Snippets:384
Trust Score:9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Configure Application Start Phase

Source: https://prom-ex.hexdocs.pm/seeding-metrics.md

Define a start phase in your `mix.exs` file to trigger telemetry seeding during application startup.

```elixir
def application do
  [
    extra_applications: [],
    mod: {MyApp.Application, []},
    start_phases: [seed_prom_ex_telemetry: []]
  ]
end
```

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

### Start PromEx.ManualMetricsManager Process

Source: https://prom-ex.hexdocs.pm/PromEx.ManualMetricsManager.md

Used to start the PromEx.ManualMetricsManager process. Accepts options for configuration.

```elixir
 @spec start_link(opts :: keyword()) :: GenServer.on_start()
```

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

### Implement Start Phase Callback

Source: https://prom-ex.hexdocs.pm/seeding-metrics.md

Add a callback function to your `MyApp.Application` module to execute the `seed_event_metrics/0` function during the specified start phase.

```elixir
defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      MyApp.PromEx
      # ... Repo, Phoenix, etc
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end

  @impl true
  def start_phase(:seed_prom_ex_telemetry, :normal, _) do
    MyApp.PromEx.seed_event_metrics()
    :ok
  end
end
```

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

### GrafanaAgent start_link

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaAgent.md

Starts the GrafanaAgent GenServer. Consult the documentation for available options.

```elixir
@spec start_link(opts :: keyword()) :: GenServer.on_start()
```

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

### start_link

Source: https://prom-ex.hexdocs.pm/PromEx.LifecycleAnnotator.md

Used to start the PromEx.LifecycleAnnotator process. It accepts options to configure the GenServer.

```APIDOC
## `start_link`

### Description

Used to start the `PromEx.LifecycleAnnotator` process. It accepts options to configure the GenServer.

### Elixir Function Signature

```elixir
@spec start_link(opts :: keyword()) :: GenServer.on_start()
```

### Parameters

#### `opts`

- **opts** (keyword) - A keyword list of options to configure the GenServer.
```

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

### Build PromEx Configuration Struct

Source: https://prom-ex.hexdocs.pm/PromEx.Config.md

Function to create a PromEx configuration struct, encapsulating all settings for starting a PromEx supervisor and its worker processes.

```elixir
@spec build(keyword()) :: t()
```

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

### Start PromEx.ETSCronFlusher Process

Source: https://prom-ex.hexdocs.pm/PromEx.ETSCronFlusher.md

Starts the PromEx.ETSCronFlusher process. This function is used to initiate the background process responsible for flushing ETS data.

```elixir
start_link(opts :: keyword()) :: GenServer.on_start()
```

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

### Configure PromEx Application

Source: https://prom-ex.hexdocs.pm/PromEx.md

Set application configuration for a PromEx module, similar to Ecto. This example shows configuration for metrics delay, dropped metrics, and Grafana integration.

```elixir
config :my_app, MyApp.PromEx,
  manual_metrics_start_delay: :no_delay,
  drop_metrics_groups: [],
  grafana:
    host: System.get_env("GRAFANA_HOST", "http://grafana:3000"),
    auth_token: System.get_env("GRAFANA_TOKEN", ""),
    upload_dashboards_on_start: true,
    folder_name: "My App Dashboards",
    annotate_app_lifecycle: true
```

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

### Configuring PromEx.Plug with Unplug

Source: https://prom-ex.hexdocs.pm/PromEx.Plug.md

Integrates PromEx.Plug into your endpoint.ex file using Unplug for conditional access. This example shows how to set a specific PromEx module and secure the metrics path.

```elixir
plug Unplug,
  if: {MyApp.UnplugPredicates.SecureMetricsEndpoint, "PROMETHEUS_AUTH_SECRET"},
  do: {PromEx.Plug, prom_ex_module: MyApp.PromEx}
```

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

### Configure PromEx with PhoenixLiveView Plugin

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.PhoenixLiveView.md

Add the PhoenixLiveView plugin to your PromEx module configuration to start collecting LiveView metrics. Ensure your otp_app is correctly set.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      PromEx.Plugins.PhoenixLiveView
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "phoenix_live_view.json"}
    ]
  end
end
```

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

### Example Plug Router Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.PlugRouter.md

Defines a Plug Router module with PromEx and Plug.Telemetry plugs. Ensure your router module is listed in the 'routers' option of the PlugRouter plugin configuration.

```elixir
defmodule WebApp.Router do
  use Plug.Router

  plug PromEx.Plug, prom_ex_module: WebApp.PromEx, path: "/metrics"
  plug Plug.Telemetry, event_prefix: [:webapp, :router]
  ...
end
```

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

### Absinthe Plugin Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Absinthe.md

Example of how to add the Absinthe plugin to your PromEx configuration. The `ignored_entrypoints` option can be used to filter out specific schema entrypoints like `__schema`.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {PromEx.Plugins.Absinthe, ignored_entrypoints: [:__schema]},
      ...
    ]
  end

  @impl true
  def dashboards do
    [
      ...,
      {:prom_ex, "absinthe.json"}
    ]
  end
end
```

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

### Add PromEx to Application Supervision Tree

Source: https://prom-ex.hexdocs.pm/

Include the generated PromEx module in your application's supervision tree in application.ex. It should be started before other services to capture initialization events.

```elixir
defmodule MyCoolApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # PromEx should be started before anything else as PromEx will caputre init events from
      # libraries like Ecto, Phoenix and Oban. If it is started after those other supervision trees
      # you will miss those events and metrics.
      MyCoolApp.PromEx,

      MyCoolApp.Repo,
      MyCoolApp.Endpoint
      ...
    ]

    opts = [strategy: :one_for_one, name: MyCoolApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end
```

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

### PromEx Module Configuration for Grafana

Source: https://prom-ex.hexdocs.pm/PromEx.DashboardUploader.md

Example of how to configure Grafana host and authentication token for a specific PromEx module within your application configuration. Ensure you replace placeholders with your actual Grafana details.

```elixir
config :web_app, WebApp.PromEx,
  grafana_host: "<YOUR HOST ADDRESS>",
  grafana_auth_token: "<YOUR GRAFANA AUTH TOKEN>"
```

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

### Define Event Metrics for a PromEx Plugin

Source: https://prom-ex.hexdocs.pm/writing-promex-plugins.md

Implement the `event_metrics/1` callback to expose event-based metrics. This example shows how to build a distribution metric for HTTP request durations in a Phoenix application.

```elixir
defmodule MyApp.PromEx.Plugins.MyPhoenix do
  use PromEx.Plugin

  @impl true
  def event_metrics(opts) do
    http_metrics_tags = gen_http_metrics_tags(opts)
    phoenix_router = get_phoenix_router(opts)
    phoenix_stop_event = [:phoenix, :endpoint, :stop]

    Event.build(
      :phoenix_http_event_metrics,
      [
        # Capture request duration information
        distribution(
          [:phoenix, :http, :request, :duration, :milliseconds],
          event_name: phoenix_stop_event,
          measurement: :duration,
          description: "The time it takes for the application to respond to HTTP requests.",
          reporter_options: [
            buckets: exponential!(1, 2, 12)
          ],
          tag_values: get_conn_tags(phoenix_router),
          tags: http_metrics_tags,
          unit: {:native, :millisecond}
        )

        # Additional event based metrics ...
      ]
    )
  end
end
```

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

### Access Application Metrics via curl

Source: https://prom-ex.hexdocs.pm/

After setup, you can access your application's metrics by sending a curl request to the /metrics endpoint. The output includes various metrics about your application and its dependencies.

```bash
$ curl localhost:4000/metrics
# HELP my_cool_app_application_dependency_info Information regarding the application's dependencies.
# TYPE my_cool_app_application_dependency_info gauge
my_cool_app_application_dependency_info{modules="69",name="hex",version="0.20.5"} 1
my_cool_app_application_dependency_info{modules="1",name="connection",version="1.0.4"} 1
my_cool_app_application_dependency_info{modules="4",name="telemetry_poller",version="0.5.1"} 1
...
```

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

### Example Phoenix Plugin Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Phoenix.md

This snippet shows a typical configuration for the PromEx Phoenix plugin. Ensure that the `endpoint`, `router`, and `event_prefix` values match your application's structure. The `normalize_event_name` function can be customized to control event name mapping.

```elixir
{
  PromEx.Plugins.Phoenix,
  endpoint: MyApp.Endpoint,
  router: MyAppWeb.Public.Router,
  event_prefix: [:admin, :endpoint],
  normalize_event_name: fn event -> event end)
}
```

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

### Get All Grafana Folders

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Retrieves a list of all folders present in Grafana. Requires an active Grafana connection.

```elixir
@spec get_all_folders(grafana_conn :: PromEx.GrafanaClient.Connection.t()) ::
  handler_response()

Get all of the folder that exist in Grafana
```

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

### Add Beam Plugin to PromEx Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Beam.md

Integrate the PromEx.Plugins.Beam into your application's PromEx module to start collecting BEAM metrics. Ensure your PromEx module is configured with the correct otp_app and includes the beam.json dashboard.

```elixir
defmodule MyApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      PromEx.Plugins.Beam
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "beam.json"}
    ]
  end
end
```

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

### PromEx Grafana Integration Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Config.md

Configure PromEx to communicate with Grafana by specifying the host, authentication credentials (username/password or auth token), and whether to upload dashboards on start.

```elixir
config :web_app, WebApp.PromEx,
  grafana:
    host: "http://localhost:3000",
    username: "<YOUR_USERNAME>", # Authenticate via Basic Auth
    password: "<YOUR_PASSWORD>",
    auth_token: "<YOUR_AUTH_TOKEN_HERE>", # Or authenticate via API Token
    upload_dashboards_on_start: true # This is an optional setting and will default to `true`
```

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

### Custom Event Name Normalization

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Phoenix.md

This example demonstrates how to use the `normalize_event_name` option to remap channel event names. It maps 'join' and 'leave' events to themselves and all other events to 'unknown', which can help reduce metric cardinality.

```elixir
fn
  "join" -> "join"
  "leave" -> "leave"
  _ -> "unknown"
end
```

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

### Default PromEx Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Config.md

This configuration represents the default settings if no PromEx configuration is provided. It disables Grafana integration and the metrics server, starts the manual metrics manager without delay, and registers all metrics groups.

```elixir
config :web_app, WebApp.PromEx,
  disabled: false,
  manual_metrics_start_delay: :no_delay,
  drop_metrics_groups: [],
  grafana: :disabled,
  metrics_server: :disabled
```

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

### Configuring PlugRouter to Ignore Routes

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.PlugRouter.md

Example of how to use the 'ignore_routes' option to prevent metrics from being collected for specific paths. This is useful for excluding internal or health check endpoints.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {PromEx.Plugins.PlugRouter,
        event_prefix: [:webapp, :router], metric_prefix: [:prom_ex, :router], routers: [WebApp.Router],
        ignore_routes: ["/metrics"]}
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "plug_router.json"}
    ]
  end
end
```

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

### Elixir Function Specification for Get Metrics

Source: https://prom-ex.hexdocs.pm/PromEx.md

Specifies the function signature for getting metrics, which returns a string or a :prom_ex_down atom.

```elixir
@spec get_metrics(prom_ex_module :: module()) :: String.t() | :prom_ex_down
```

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

### PromEx.Config.build/1

Source: https://prom-ex.hexdocs.pm/PromEx.Config.md

Creates a configuration struct (`t()`) that encapsulates all necessary settings for initializing a PromEx supervisor and its associated worker processes.

```APIDOC
## Function: build/1

```elixir
@spec build(keyword()) :: t()
```

### Description

Creates a struct that encapsulates all of the configuration needed to start a PromEx supervisor instance as well as all of the worker processes.

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```elixir
# Example usage (assuming keyword list format for configuration)
PromEx.Config.build([disabled: false, ets_flush_interval: 1000])
```

### Response

#### Success Response (t())

Returns a `%PromEx.Config{}` struct populated with the provided configuration.

#### Response Example

```elixir
# Example of a returned struct
%PromEx.Config{
  disabled: false,
  drop_metrics_groups: MapSet.new(),
  ets_flush_interval: 1000,
  grafana_agent_config: %{},
  grafana_config: %{},
  manual_metrics_start_delay: :no_delay,
  metrics_server_config: %{}
}
```
```

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

### GrafanaAgent child_spec

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaAgent.md

Returns a specification to start the PromEx.GrafanaAgent module under a supervisor.

```elixir
child_spec() :: Supervisor.child_spec()
```

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

### Add PromEx Application Plugin to Supervision Tree

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Application.md

Integrate the PromEx.Plugins.Application into your application's supervision tree. Ensure PromEx's `:delay_manual_start` is configured appropriately for manual metrics.

```elixir
def start(_type, _args) do
  children = [
    ...
    {
      PromEx,
      plugins: [
        {PromEx.Plugins.Application, [otp_app: :my_cool_app]},
        ...
      ],
      delay_manual_start: :no_delay
    }
  ]

  opts = [strategy: :one_for_one, name: WebApp.Supervisor]
  Supervisor.start_link(children, opts)
end
```

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

### PromEx.LifecycleAnnotator child_spec

Source: https://prom-ex.hexdocs.pm/PromEx.LifecycleAnnotator.md

Returns a specification to start the PromEx.LifecycleAnnotator module under a supervisor. Consult `Supervisor` for more details.

```elixir
def child_spec, do: Supervisor.child_spec(__MODULE__)
```

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

### Elixir Callback Specification for Init Options

Source: https://prom-ex.hexdocs.pm/PromEx.md

Specifies a callback for retrieving initialization options, returning a PromEx configuration type.

```elixir
@callback init_opts() :: PromEx.Config.t()
```

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

### Get Grafana Folder

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Fetches the details of a specific folder in Grafana using its UID. Requires the Grafana connection and the folder's UID.

```elixir
@spec get_folder(
  grafana_conn :: PromEx.GrafanaClient.Connection.t(),
  folder_uid :: String.t()
) ::
  handler_response()

Used to fetch the details regarding a particular folder on Grafana
```

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

### Configure PromEx to Use Peep Storage Adapter

Source: https://prom-ex.hexdocs.pm/PromEx.md

Add this configuration to your `config.exs` file to use Peep as the storage adapter for PromEx. This requires the Peep library to be added as a dependency.

```elixir
config :prom_ex, :storage_adapter, PromEx.Storage.Peep
```

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

### PromEx Storage Child Spec Generation

Source: https://prom-ex.hexdocs.pm/PromEx.Storage.md

Generates the process child specification for the store. This function is used to create the necessary configuration for starting the storage process.

```elixir
@spec child_spec(
  mod :: module(),
  name :: module(),
  metrics :: [Telemetry.Metrics.t()]
) ::
  Supervisor.child_spec()
```

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

### ApacheBench Results With PromEx

Source: https://prom-ex.hexdocs.pm/

Results from an ApacheBench stress test on an application with PromEx metrics collection enabled. Shows metrics like requests per second and connection times.

```text
$ ./benchmarks/ab-graph.sh -u http://localhost:4000 -n 1000 -c 50 -k
Server Software:        Cowboy
Server Hostname:        localhost
Server Port:            4000

Document Path:          /
Document Length:        3389 bytes

Concurrency Level:      50
Time taken for tests:   4.144 seconds
Complete requests:      1000
Failed requests:        0
Keep-Alive requests:    1000
Total transferred:      4060000 bytes
HTML transferred:       3389000 bytes
Requests per second:    241.32 [#/sec] (mean)
Time per request:       207.191 [ms] (mean)
Time per request:       4.144 [ms] (mean, across all concurrent requests)
Transfer rate:          956.81 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.2      0       1
Processing:    39  202  24.3    203     264
Waiting:       38  202  24.3    203     264
Total:         39  202  24.2    203     264

Percentage of the requests served within a certain time (ms)
  50%    203
  66%    210
  75%    215
  80%    218
  90%    227
  95%    237
  98%    246
  99%    255
 100%    264 (longest request)

```

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

### build

Source: https://prom-ex.hexdocs.pm/PromEx.DashboardRenderer.md

Reads the contents of a dashboard file entry, prioritizing EEx versions if they exist.

```APIDOC
## `build`

### Description
Reads the contents of a dashboard file entry. If an EEx version of the file exists, it is read; otherwise, it falls back to the provided file name. This is convenient for using EEx templates without explicitly writing `.eex`.

### Function Signature
`build(dashboard_otp_app :: atom(), dashboard_relative_path :: String.t(), metrics_otp_app :: atom()) :: t()`

### Parameters
- `dashboard_otp_app` (atom): The OTP application name for the dashboard.
- `dashboard_relative_path` (String.t): The relative path to the dashboard file.
- `metrics_otp_app` (atom): The OTP application name for the metrics.

### Returns
- `t()`: A `PromEx.DashboardRenderer` struct containing the read file contents.
```

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

### PromEx Storage Child Spec Callback

Source: https://prom-ex.hexdocs.pm/PromEx.Storage.md

Defines the child specification for a gatherer process. This callback is used to configure how the gatherer process is started and managed within a supervision tree.

```elixir
@callback child_spec(atom(), [Telemetry.Metrics.t()]) :: Supervisor.child_spec()
```

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

### Get Grafana Dashboard

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Fetches the JSON definition of a dashboard currently existing in Grafana. Requires the connection and the dashboard file path. Returns an error tuple if the dashboard ID does not exist.

```elixir
@spec get_dashboard(
  grafana_conn :: PromEx.GrafanaClient.Connection.t(),
  dashboard_file_path :: String.t()
) :: handler_response()

Used to get the dashboard definition currently in Grafana for the provided dashboard file.
If the ID does not exist in Grafana an error tuple will be returned.
```

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

### Basic PlugCowboy Plugin Integration

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.PlugCowboy.md

Integrate the PlugCowboy plugin into your PromEx module. Ensure to replace `MyApp.Router` with your actual router module and `:web_app` with your OTP application's name.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {PromEx.Plugins.PlugCowboy, routers: [MyApp.Router]}
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "plug_cowboy.json"}
    ]
  end
end
```

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

### Generate PromEx Configuration

Source: https://prom-ex.hexdocs.pm/

Run the mix task to generate the PromEx configuration file. Replace YOUR_PROMETHEUS_DATASOURCE_ID with your Grafana data source name.

```bash
$ mix prom_ex.gen.config --datasource YOUR_PROMETHEUS_DATASOURCE_ID
```

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

### Build Grafana Client Connection

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Builds a connection object for interacting with the Grafana API. Requires the PromEx module as an argument.

```elixir
@spec build_conn(prom_ex_module :: module()) :: PromEx.GrafanaClient.Connection.t()

Build a grafana client connection.
```

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

### linear!

Source: https://prom-ex.hexdocs.pm/PromEx.BucketGenerator.md

Create a linear set of buckets based on the provided parameters.

```APIDOC
## linear!

### Description
Create a linear set of buckets based on the provided parameters.

### Method
`PromEx.BucketGenerator.linear/3`

### Parameters
#### Path Parameters
- `start` (number) - Description of the starting value for the bucket generation.
- `step` (number) - Description of the increment for linear growth.
- `num_buckets` (number) - Description of the total number of buckets to generate.

### Request Example
```elixir
PromEx.BucketGenerator.linear!(10, 10, 10)
```

### Response
#### Success Response
- `[non_neg_integer()]` - A list of non-negative integers representing the bucket ranges.
```

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

### Define Manual Metrics in PromEx Plugin

Source: https://prom-ex.hexdocs.pm/writing-promex-plugins.md

This function defines manual metrics for a PromEx plugin. It uses `Manual.build/3` to set up metrics that are measured by a specified MFA (Module, Function, Arity) and updated manually.

```elixir
defmodule PromEx.Plugins.Application do
  use PromEx.Plugin

  @impl true
  def manual_metrics(opts) do
    otp_app = Keyword.fetch!(opts, :otp_app)
    apps = Keyword.get(opts, :deps, :all)

    Manual.build(
      :application_versions_manual_metrics,
      {__MODULE__, :apps_running, [otp_app, apps]},
      [
        # Capture information regarding the primary application (i.e the user's application)
        last_value(
          [otp_app | [:application, :primary, :info]],
          event_name: [otp_app | [:application, :primary, :info]],
          description: "Information regarding the primary application.",
          measurement: :status,
          tags: [:name, :version, :modules]
        )

        # Additional metrics here
      ]
    )
  end

  @doc false
  def apps_running(otp_app, apps) do
    ...

    # Emit primary app details
    :telemetry.execute(
      [otp_app | [:application, :primary, :info]],
      %{ 
        status: if(Map.has_key?(started_apps, otp_app), do: 1, else: 0)
      },
      %{ 
        name: otp_app,
        version:
          Map.get_lazy(started_apps, otp_app, fn ->
            Map.get(loaded_only_apps, otp_app, "undefined")
          end),
        modules: length(Application.spec(otp_app)[:modules])
      }
    )
  end
end
```

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

### Generate Distinct PromEx Configurations

Source: https://prom-ex.hexdocs.pm/running-multiple-agents.md

Use these Mix tasks to generate separate PromEx configuration modules for different teams or purposes.

```shell
mix prom_ex.gen.config -d ops -m PromExOps
mix prom_ex.gen.config -d biz -m PromExBiz
```

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

### exponential!

Source: https://prom-ex.hexdocs.pm/PromEx.BucketGenerator.md

Create an exponential set of buckets based on the provided parameters.

```APIDOC
## exponential!

### Description
Create an exponential set of buckets based on the provided parameters.

### Method
`PromEx.BucketGenerator.exponential/3`

### Parameters
#### Path Parameters
- `start` (number) - Description of the starting value for the bucket generation.
- `factor` (number) - Description of the multiplication factor for exponential growth.
- `num_buckets` (number) - Description of the total number of buckets to generate.

### Request Example
```elixir
PromEx.BucketGenerator.exponential!(1, 4, 10)
```

### Response
#### Success Response
- `[non_neg_integer()]` - A list of non-negative integers representing the bucket ranges.
```

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

### Add Ecto Plugin to PromEx Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Ecto.md

Include this snippet in your PromEx module's `plugins/0` function to enable Ecto metric collection. Ensure PromEx is supervised before your Ecto Repo to capture all initialization events.

```elixir
def plugins do
  [
    ...

    {PromEx.Plugins.Ecto, otp_app: :web_app, repos: [WebApp.Repo]}
  ]
end

```

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

### PromEx.MetricTypes.Manual Build Function Signature

Source: https://prom-ex.hexdocs.pm/PromEx.MetricTypes.Manual.md

Specifies the signature for the `build` function, used to create a PromEx.MetricTypes.Manual struct.

```elixir
@spec build(
  group_name :: atom(),
  measurements_mfa :: PromEx.measurements_mfa(),
  metrics :: [PromEx.telemetry_metrics()]
) :: t()
```

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

### Configure Unique Ports and Directories for Multiple Agents

Source: https://prom-ex.hexdocs.pm/running-multiple-agents.md

Configure distinct `working_directory`, `agent_port`, and `grpc_port` for each PromEx module to prevent collisions when running multiple agents.

```elixir
config :my_app, MyApp.PromExOps,
  grafana_agent: [
    working_directory: System.fetch_env!("RELEASE_TMP") <> "/grafana-ops",
    config_opts: [
      ...
      agent_port: 4040,
      grpc_port: 9040
    ]
  ]

config :my_app, MyApp.PromExBiz,
  grafana_agent: [
    working_directory: System.fetch_env!("RELEASE_TMP") <> "/grafana-biz",
    config_opts: [
      ...
      agent_port: 4041,
      grpc_port: 9041
    ]
  ]
```

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

### manual_metrics

Source: https://prom-ex.hexdocs.pm/PromEx.Plugin.md

The `manual_metrics/1` callback is used to retrieve manual-based metrics configured for a plugin. It can return a single manual metric or a list of them. A default implementation returning an empty list is provided if no manual metrics are exposed.

```APIDOC
## `manual_metrics/1`

### Description
This callback returns the configured manual-based metrics that the plugin exposes. If the plugin does not expose any manual-style metrics, a default implementation returns an empty list.

### Callback
`manual_metrics(keyword()) :: [PromEx.MetricTypes.Manual.t()] | PromEx.MetricTypes.Manual.t()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **metrics** (list of PromEx.MetricTypes.Manual.t() | PromEx.MetricTypes.Manual.t()) - The manual metrics exposed by the plugin.

### Response Example
None
```

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

### Manual Metrics Callback Definition

Source: https://prom-ex.hexdocs.pm/PromEx.Plugin.md

Defines the `manual_metrics` callback signature. Plugins should return a single or list of `PromEx.Plugins.Manual` structs.

```elixir
@callback manual_metrics(keyword()) ::
  [PromEx.MetricTypes.Manual.t()] | PromEx.MetricTypes.Manual.t()
```

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

### PromEx Module Configuration with PlugRouter Plugin

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.PlugRouter.md

Integrates the PlugRouter plugin into your PromEx module. Specify required options like event_prefix, metric_prefix, and routers. The routers option should contain the module names of your Plug Routers.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  alias PromEx.Plugins

  @impl true
  def plugins do
    [
      ...
      {Plugins.PlugRouter,
        event_prefix: [:webapp, :router], metric_prefix: [:prom_ex, :router], routers: [WebApp.Router]}
    ]
  end

  @impl true
  def dashboard_assigns do
    [
      datasource_id: "...",
      plug_router_metric_prefix: "prom_ex_router"
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "plug_router.json"}
    ]
  end
end
```

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

### Create Grafana Folder

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Creates a new folder in Grafana. Requires a connection, folder UID, and a title for the new folder.

```elixir
@spec create_folder(
  grafana_conn :: PromEx.GrafanaClient.Connection.t(),
  folder_uid :: String.t(),
  title :: String.t()
) :: handler_response()

Used to create a new folder in Grafana
```

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

### render_dashboard

Source: https://prom-ex.hexdocs.pm/PromEx.DashboardRenderer.md

Renders the dashboard, passing PromEx module assigns for EEx files or passing raw JSON untouched.

```APIDOC
## `render_dashboard`

### Description
Renders the dashboard. If it is an EEx file, then the PromEx module assigns are passed. Else if it is a raw JSON file, then it is passed through untouched.

### Function Signature
`render_dashboard(t(), prom_ex_module :: module()) :: t()`

### Parameters
- `t()`: The dashboard renderer struct.
- `prom_ex_module` (module()): The PromEx module to use for rendering (primarily for EEx files).

### Returns
- `t()`: The dashboard renderer struct with the rendered dashboard content.
```

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

### build/2

Source: https://prom-ex.hexdocs.pm/PromEx.MetricTypes.Event.md

The `build/2` function creates a PromEx.MetricTypes.Event struct, which encapsulates a group of event-based metrics. It requires a unique `group_name` and a list of `metrics`.

```APIDOC
## `build`

```elixir
@spec build(group_name :: atom(), metrics :: [PromEx.telemetry_metrics()]) :: t()
```

Create a struct that encompasses a group of event based metrics. The `group_name` should be unique and should follow
the following convention: `<APPLICATION>_<SHORT DESCRIPTION>_event_metrics`. For example, Phoenix HTTP related metrics
have a `group_name` of: `:phoenix_http_event_metrics`
```

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

### PromEx.MetricTypes.Manual.build/3

Source: https://prom-ex.hexdocs.pm/PromEx.MetricTypes.Manual.md

Creates a PromEx.MetricTypes.Manual struct, which defines a group of manually triggered metrics. It requires a unique group name, an MFA tuple for measurements, and a list of Telemetry Metrics structs.

```APIDOC
## build/3

### Description
Creates a struct that encompasses a group of manually triggered metrics. The `group_name` should be unique and should follow the following convention: `<APPLICATION>_<SHORT DESCRIPTION>_manual_metrics`. For example, Application related info metrics have a `group_name` of: `:application_versions_manual_metrics`

### Function Signature
```elixir
build(group_name :: atom(), measurements_mfa :: PromEx.measurements_mfa(), metrics :: [PromEx.telemetry_metrics()]) :: %PromEx.MetricTypes.Manual{}
```

### Parameters
#### Arguments
- `group_name` (atom()) - A unique identifier for the collection of metrics.
- `measurements_mfa` (PromEx.measurements_mfa()) - An MFA tuple that defines what function will be executed that will emit Telemetry events.
- `metrics` ([PromEx.telemetry_metrics()]) - A list of Telemetry Metrics structs that define the metrics.
```

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

### Configure Single Endpoint for Shared Metrics

Source: https://prom-ex.hexdocs.pm/running-multiple-agents.md

Configure a single endpoint to scrape metrics for a specific PromEx module. Ensure `metrics_server_path` is set in your Mix configuration.

```elixir
# endpoint.ex
plug PromEx.Plug, prom_ex_module: MyApp.PromExOps

# in mix config, set `metrics_server_path: "/metrics"`
```

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

### Generate GrafanaAgent Config File

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaAgent.ConfigRenderer.md

Use this function to generate and write the GrafanaAgent configuration file. It takes options and the configuration directory as arguments.

```elixir
@spec generate_config_file(opts :: map(), config_dir :: String.t()) :: String.t()
```

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

### PromEx Metrics Server Configuration

Source: https://prom-ex.hexdocs.pm/PromEx.Config.md

Enable and configure a standalone HTTP metrics server for PromEx. Specify the port, path, protocol, connection pool size, Cowboy options, and authentication strategy.

```elixir
config :web_app, WebApp.PromEx,
  metrics_server:
    port: 4021,
    path: "/metrics", # This is an optional setting and will default to `"/metrics"`
    protocol: :http, # This is an optional setting and will default to `:http`
    pool_size: 5, # This is an optional setting and will default to `5`
    cowboy_opts: [], # This is an optional setting and will default to `[]`
    auth_strategy: :none # This is an optional and will default to `:none`
```

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

### Seed Event Metrics

Source: https://prom-ex.hexdocs.pm/seeding-metrics.md

Implement the `seed_event_metrics/0` function to emit desired telemetry events with specific measurements and metadata. This ensures the metrics server path is fully populated.

```elixir
def seed_event_metrics do
  # :telemetry.execute([:my_app, :event], %{}, %{status: :ok})
  # :telemetry.execute([:my_app, :event], %{}, %{status: :error})
  # :telemetry.execute([:my_app, :event_span, :start], %{count: 1}, %{})
  # :telemetry.execute([:my_app, :event_span, :stop], %{count: 1}, %{})
  # :telemetry.execute([:my_app, :event_span, :exception], %{count: 1}, %{})

  :ok
end
```

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

### Build Grafana Connection Struct

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.Connection.md

Builds a connection struct for connecting to Grafana using a Finch process and Grafana configuration.

```elixir
@spec build(finch_process :: module(), grafana_config :: map()) :: t()
```

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

### ApacheBench Results Without PromEx

Source: https://prom-ex.hexdocs.pm/

Results from an ApacheBench stress test on an application without PromEx metrics collection. Used for comparison to assess PromEx's performance impact.

```text
$ ./benchmarks/ab-graph.sh -u http://localhost:4000 -n 1000 -c 50 -k
Server Software:        Cowboy
Server Hostname:        localhost
Server Port:            4000

Document Path:          /
Document Length:        3389 bytes

Concurrency Level:      50
Time taken for tests:   4.156 seconds
Complete requests:      1000
Failed requests:        0
Keep-Alive requests:    1000
Total transferred:      4060000 bytes
HTML transferred:       3389000 bytes
Requests per second:    240.59 [#/sec] (mean)
Time per request:       207.822 [ms] (mean)
Time per request:       4.156 [ms] (mean, across all concurrent requests)
Transfer rate:          953.90 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.1      0       1
Processing:    38  202  23.1    205     267
Waiting:       37  202  23.1    205     267
Total:         38  202  23.0    205     267

Percentage of the requests served within a certain time (ms)
  50%    205
  66%    211
  75%    215
  80%    219
  90%    226
  95%    232
  98%    238
  99%    246
 100%    267 (longest request)

```

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

### PromEx.GrafanaClient.Connection.build/2

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.Connection.md

Builds a connection struct required for connecting to a Grafana instance. This function takes the Finch process and Grafana configuration as input and returns a fully formed Connection struct.

```APIDOC
## `build/2`

### Description
Builds a connection struct for connecting to Grafana.

### Function Signature
```elixir
@spec build(finch_process :: module(), grafana_config :: map()) :: %PromEx.GrafanaClient.Connection{}
```

### Parameters
#### Function Parameters
- `finch_process` (module()) - The Finch process to be used for communication.
- `grafana_config` (map()) - A map containing the configuration details for Grafana.

### Returns
- `%PromEx.GrafanaClient.Connection{}` - A struct containing the necessary data to connect to a Grafana instance.
```

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

### Generate Linear Buckets

Source: https://prom-ex.hexdocs.pm/PromEx.BucketGenerator.md

Creates a linear series of bucket boundaries. Suitable for metrics with a consistent range of values.

```elixir
iex> PromEx.BucketGenerator.linear!(10, 10, 10)
[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
```

```elixir
iex> PromEx.BucketGenerator.linear!(0, 250, 11)
[0, 250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500]
```

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

### Generate Exponential Buckets

Source: https://prom-ex.hexdocs.pm/PromEx.BucketGenerator.md

Creates an exponential series of bucket boundaries. Useful for metrics where values grow rapidly.

```elixir
iex> PromEx.BucketGenerator.exponential!(1, 4, 10)
[1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144]
```

```elixir
iex> PromEx.BucketGenerator.exponential!(1, 2, 10)
[1, 2, 4, 8, 16, 32, 64, 128, 256, 512]
```

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

### Build Dashboard Renderer

Source: https://prom-ex.hexdocs.pm/PromEx.DashboardRenderer.md

Reads dashboard file contents, prioritizing EEx versions over JSON. This function is used to initialize the DashboardRenderer struct.

```elixir
@spec build(
  dashboard_otp_app :: atom(),
  dashboard_relative_path :: String.t(),
  metrics_otp_app :: atom()
) :: t()
```

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

### get_metrics

Source: https://prom-ex.hexdocs.pm/PromEx.md

Fetches all currently configured metrics from a given PromEx module. This function is mainly utilized by the exporter plug to retrieve metrics for scraping.

```APIDOC
## get_metrics

### Description
A simple pass-through to fetch all of the currently configured metrics. This is primarily used by the exporter plug to fetch all of the metrics so that they can be scraped.

### Function Signature
`get_metrics(prom_ex_module :: module()) :: String.t() | :prom_ex_down`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **metrics** (String.t() | :prom_ex_down) - A string containing the metrics or :prom_ex_down atom if the exporter is down.
```

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

### Render Dashboard

Source: https://prom-ex.hexdocs.pm/PromEx.DashboardRenderer.md

Renders the dashboard. Passes PromEx module assigns for EEx files or passes raw JSON files through untouched.

```elixir
@spec render_dashboard(t(), prom_ex_module :: module()) :: t()
```

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

### Add PromEx to Mix Dependencies

Source: https://prom-ex.hexdocs.pm/

Add the prom_ex package to your project's dependencies in mix.exs. Ensure you use a compatible version.

```elixir
def deps do
  [
    {:prom_ex, "~> 1.11.0"}
  ]
end
```

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

### scrape (module function)

Source: https://prom-ex.hexdocs.pm/PromEx.Storage.md

Extracts metrics from the configured store for a given module and name.

```APIDOC
## `scrape` (module function)

### Description
Extracts metrics from the configured store.

### Function Signature
```elixir
@spec scrape(mod :: module(), name :: module()) :: iodata() | :prom_ex_down
```
```

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

### Define PromEx Module

Source: https://prom-ex.hexdocs.pm/PromEx.md

Define a module that uses PromEx and specifies the OTP application. This is a foundational step for integrating PromEx into your application.

```elixir
defmodule MyApp.PromEx do
  use PromEx,  otp_app: :web_app

  ...
end
```

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

### create_folder

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Creates a new folder in Grafana to organize dashboards.

```APIDOC
## create_folder

### Description
Used to create a new folder in Grafana

### Function Signature
```elixir
@spec create_folder(
  grafana_conn :: PromEx.GrafanaClient.Connection.t(),
  folder_uid :: String.t(),
  title :: String.t()
) :: handler_response()
```
```

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

### Elixir Callback Specification for Plugins

Source: https://prom-ex.hexdocs.pm/PromEx.md

Specifies a callback for retrieving a list of plugin definitions.

```elixir
@callback plugins() :: [plugin_definition()]
```

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

### build_conn

Source: https://prom-ex.hexdocs.pm/PromEx.GrafanaClient.md

Builds a Grafana client connection. This is a prerequisite for most other operations.

```APIDOC
## build_conn

### Description
Builds a Grafana client connection.

### Function Signature
```elixir
@spec build_conn(prom_ex_module :: module()) :: PromEx.GrafanaClient.Connection.t()
```
```

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

### Configure PromEx with Single Phoenix Router

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Phoenix.md

Add this configuration to your PromEx module to integrate the Phoenix plugin with a single endpoint and router. Ensure the `otp_app`, `endpoint`, and `router` options are correctly set for your application.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {
        PromEx.Plugins.Phoenix,
        endpoint: MyApp.Endpoint,
        router: MyAppWeb.Public.Router
      }
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "phoenix.json"}
    ]
  end
end
```

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

### Configure PromEx with Multiple Phoenix Routers

Source: https://prom-ex.hexdocs.pm/PromEx.Plugins.Phoenix.md

Use the `endpoints` option when configuring the Phoenix plugin if your application manages multiple Phoenix routers. This allows specifying different routers and event prefixes for each endpoint.

```elixir
defmodule WebApp.PromEx do
  use PromEx, otp_app: :web_app

  @impl true
  def plugins do
    [
      ...
      {
        PromEx.Plugins.Phoenix,
        endpoints: [
          {MyApp.Endpoint, routers: [MyAppWeb.Public.Router]},
          {MyApp.Endpoint2, routers: [MyAppWeb.Admin.Router], event_prefix: [:admin, :endpoint]}
        ]
      }
    ]
  end

  @impl true
  def dashboards do
    [
      ...
      {:prom_ex, "phoenix.json"}
    ]
  end
end
```

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

### Event Metrics Callback Definition

Source: https://prom-ex.hexdocs.pm/PromEx.Plugin.md

Defines the `event_metrics` callback signature. Plugins should return a single or list of `PromEx.Plugins.Event` structs.

```elixir
@callback event_metrics(keyword()) ::
  [PromEx.MetricTypes.Event.t()] | PromEx.MetricTypes.Event.t()
```
Tokens:
Raw