Telemetry Metrics

https://telemetry-metrics.hexdocs.pm/
Admin
Telemetry Metrics provides a common interface for defining metrics based on telemetry events,...
Tokens:12,459
Snippets:174
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start Reporter with Metric Definitions

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Example of starting a process-based reporter with a list of metric definitions.

```Elixir
metrics = [
  counter("..."),
  last_value("..."),
  summary("...")
]

PigeonReporter.start_link(metrics: metrics)
```

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

### Start ConsoleReporter with Metrics

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

This snippet shows how to define a list of metrics and start the Telemetry.Metrics.ConsoleReporter in a supervision tree. The ConsoleReporter prints metric data to the terminal.

```elixir
metrics = [
  last_value("my_app.worker.memory", unit: :byte),
  last_value("my_app.worker.message_queue_len"),
  last_value("my_app.users.total")
]

Supervisor.start_link([
  {Telemetry.Metrics.ConsoleReporter, metrics: metrics}
], strategy: :one_for_one)
```

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

### Start Console Reporter

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.ConsoleReporter.html

Starts the Telemetry.Metrics.ConsoleReporter as a child process in a supervision tree. Requires a list of metrics to be provided during initialization.

```elixir
{Telemetry.Metrics.ConsoleReporter, metrics: metrics}
```

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

### Console Reporter Output Example

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.ConsoleReporter.html

An example of the output generated by the Telemetry.Metrics.ConsoleReporter when a 'vm.memory' telemetry event is dispatched. It shows the event details, measurements, and metadata for each registered metric.

```text
[Telemetry.Metrics.ConsoleReporter] Got new event!
Event name: vm.memory
All measurements: %{binary: 100, total: 200}
All metadata: %{}

Metric measurement: :binary (last_value)
With value: 100 byte
And tag values: %{}

Metric measurement: :total (counter)
With value: 200
And tag values: %{}
```

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

### Implement Custom Measurement Function

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Implement a function to execute custom telemetry events. This example defines `measure_users/0` to report user counts.

```elixir
defmodule MyApp do
  def measure_users do
    :telemetry.execute([:my_app, :users], %{total: MyApp.users_count()}, %{})
  end
end
```

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

### Define Custom Periodic Measurements

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Configure custom periodic measurements using :telemetry_poller, specifying the measurements and the period. This example tracks process info and custom user counts.

```elixir
measurements = [
  {:process_info,
   event: [:my_app, :worker],
   name: MyApp.Worker,
   keys: [:message_queue_len, :memory]},

  {MyApp, :measure_users, []}
]

Supervisor.start_link([
  # Run the given measurements every 10 seconds
  {:telemetry_poller, measurements: measurements(), period: 10_000}
], strategy: :one_for_one)
```

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

### Emit Telemetry Event

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Example of emitting a Telemetry event with measurement data. This is the type of event that Telemetry.Metrics can process.

```elixir
:telemetry.execute([:http, :request, :stop], %{duration: duration})
```

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

### Keep Events Matching Specific Metadata

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Use the :keep option with a predicate function to include only specific events for a metric. This example keeps events where the client metadata name is :fast_client.

```elixir
distribution(
  "http.fast.client.request.duration",
  event_name: [:http_client, :request, :stop],
  keep: &(match?(%{name: :fast_client}, &1))
)
```

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

### Define Metrics for Custom Events

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Define Telemetry.Metrics for custom events generated by your pollers. This example sets up metrics for worker memory, message queue length, and user counts.

```elixir
last_value("my_app.worker.memory", unit: :byte)
```

```elixir
last_value("my_app.worker.message_queue_len")
```

```elixir
last_value("my_app.users.total")
```

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

### Drop Events Matching Specific Metadata

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Use the :drop option with a predicate function to exclude events from a metric. This example drops events where the client metadata name is :fast_client.

```elixir
distribution(
  "http.client.request.duration",
  event_name: [:http_client, :request, :stop],
  drop: &(match?(%{name: :fast_client}, &1))
)
```

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

### reporter_options()

Source: https://telemetry-metrics.hexdocs.pm/

Keyword list for specifying options related to how metrics are reported.

```APIDOC
## Type: reporter_options()

### Description
Options for reporters, typically provided as a keyword list.

### Definition
```elixir
@type reporter_options() :: keyword()
```
```

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

### Add Telemetry Dependencies

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Add the necessary telemetry libraries to your project's dependencies.

```elixir
[
  {:telemetry_poller, "~> 0.4"},
  {:telemetry_metrics, "~> 0.4"}
]
```

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

### Define Multiple Metric Options

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Represents a list of metric options. Use this when configuring multiple settings for a single metric.

```elixir
@type metric_options() :: [metric_option()]
```

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

### metric_options()

Source: https://telemetry-metrics.hexdocs.pm/

Represents a list of metric options, used for configuring multiple aspects of a telemetry metric.

```APIDOC
## Type: metric_options()

### Description
Represents a list of `metric_option()` types.

### Definition
```elixir
@type metric_options() :: [metric_option()]
```
```

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

### Define VM Metrics

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Consume VM events like memory usage and run queue lengths using Telemetry.Metrics. Define metrics for these events to track VM performance.

```elixir
last_value("vm.memory.total", unit: :byte)
```

```elixir
last_value("vm.total_run_queue_lengths.total")
```

```elixir
last_value("vm.total_run_queue_lengths.cpu")
```

```elixir
last_value("vm.total_run_queue_lengths.io")
```

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

### Define Reporter Options

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies keyword list options for telemetry reporters. Use this to configure how metrics are reported.

```elixir
@type reporter_options() :: keyword()
```

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

### summary(metric_name, options)

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition of a summary metric. This metric aggregates measurement's values into statistics, such as minimum, maximum, mean, or percentiles.

```APIDOC
## summary(metric_name, options)

### Description
Returns a definition of a summary metric. This metric aggregates measurement's values into statistics, e.g. minimum and maximum, mean, or percentiles. It is up to the reporter to decide which statistics exactly are exposed.

### Function Signature
```elixir
summary(metric_name(), metric_options()) :: Telemetry.Metrics.Summary.t()
```

### Example
```elixir
summary("db.query.duration", tags: [:table], unit: {:native, :millisecond})
```
```

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

### Define Tags List

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Represents a list of tags. Use this to associate multiple categories with a metric.

```elixir
@type tags() :: [tag()]
```

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

### Define Metric Options

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies the available options for configuring a single telemetry metric. Use this to set event names, measurements, tags, descriptions, units, and reporter options.

```elixir
@type metric_option() ::
  {:event_name, String.t() | :telemetry.event_name()}
  | {:measurement, measurement()}
  | {:tags, tags()}
  | {:tag_values, tag_values()}
  | {:keep, keep()}
  | {:drop, drop()}
  | {:description, description()}
  | {:unit, unit() | time_unit_conversion() | byte_unit_conversion()}
  | {:reporter_options, reporter_options()}
```

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

### Define a Counter Metric with Tags

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Define a counter metric that tracks database query durations, broken down by table and operation. Ensure that the emitted events include 'table' and 'operation' keys in their metadata.

```elixir
counter("db.query.duration", tags: [:table, :operation])
```

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

### summary/2

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a summary metric. This metric aggregates measurement's values into statistics, such as minimum, maximum, mean, or percentiles.

```APIDOC
## summary/2

### Description
Returns a definition of summary metric. This metric aggregates measurement's values into statistics, e.g. minimum and maximum, mean, or percentiles. It is up to the reporter to decide which statistics exactly are exposed.

### Function Signature
`summary(metric_name(), metric_options()) :: Telemetry.Metrics.Summary.t()`

### Parameters
- `metric_name`: The name of the metric.
- `options`: A map of options for the metric, such as `tags` and `unit`.

### Example
```
summary(
  "db.query.duration",
  tags: [:table],
  unit: {:native, :millisecond}
)
```
```

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

### time_unit()

Source: https://telemetry-metrics.hexdocs.pm/

Defines the possible units for time measurements, including second, millisecond, microsecond, nanosecond, and native.

```APIDOC
## Type: time_unit()

### Description
Defines the units for time measurements.

### Definition
```elixir
@type time_unit() :: :second | :millisecond | :microsecond | :nanosecond | :native
```
```

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

### Elixir Reporter handle_event Callback

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Implements the core logic for handling incoming telemetry events. It iterates through metrics, checks recording rules, extracts measurements and tags, and handles potential errors during processing.

```Elixir
def handle_event(_event_name, measurements, metadata, metrics) do
  for metric <- metrics do
    try do
      if measurement = keep?(metric, metadata) && extract_measurement(metric, measurements) do
        tags = extract_tags(metric, metadata)

        # record and send
      end
    rescue
      e ->
        Logger.error("Could not format metric #{inspect metric}")
        Logger.error(Exception.format(:error, e, __STACKTRACE__))
    end
  end
end
```

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

### Define Description Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies that a description can be a string or nil.

```Elixir
@type description() :: nil | String.t()
```

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

### Define Metric with Unit Conversion

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Use the `:unit` option with a tuple to specify the conversion from one unit to another. Supported conversions include time and bytes.

```elixir
summary("http.request.stop.duration", unit: {from_unit, to_unit})
```

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

### Define a Summary Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a summary metric. Use this to aggregate measurement values into statistics like min, max, mean, or percentiles. Supports tags and units.

```Elixir
@spec summary(metric_name(), metric_options()) :: Telemetry.Metrics.Summary.t()
```

```Elixir
summary(
  "db.query.duration",
  tags: [:table],
  unit: {:native, :millisecond}
)
```

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

### Convert Time Units for Metrics

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Convert time measurements from the native unit to a desired precision like milliseconds. Supported time units are :second, :millisecond, :microsecond, :nanosecond, and :native.

```elixir
summary("http.request.stop.duration", unit: {:native, :millisecond})
```

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

### Convert Byte Units for Metrics

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Convert byte measurements to other units like megabytes. Supported byte units are :byte, :kilobyte, and :megabyte.

```elixir
last_value("vm.memory.total", unit: {:byte, :megabyte})
```

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

### Add Telemetry Dependencies

Source: https://telemetry-metrics.hexdocs.pm/

Add the `:telemetry_poller` and `:telemetry_metrics` packages to your project's dependencies in `mix.exs`.

```elixir
[{:telemetry_poller, "~> 0.4"},
 {:telemetry_metrics, "~> 0.4"}]
```

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

### Metric Name to Event and Measurement Mapping

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Illustrates how a metric name string is mapped to a Telemetry event name and a measurement key. The event name is typically all but the last segment of the metric name, and the measurement is the last segment.

```elixir
[:http , :request, :stop]      :duration
```

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

### metric_option()

Source: https://telemetry-metrics.hexdocs.pm/

Defines a single option for configuring a telemetry metric. This can include event names, measurements, tags, descriptions, units, and reporter-specific options.

```APIDOC
## Type: metric_option()

### Description
Represents a single configuration option for a telemetry metric.

### Definition
```elixir
@type metric_option() ::
  {:event_name, String.t() | :telemetry.event_name()} |
  {:measurement, measurement()} |
  {:tags, tags()} |
  {:tag_values, tag_values()} |
  {:keep, keep()} |
  {:drop, drop()} |
  {:description, description()} |
  {:unit, unit() | time_unit_conversion() | byte_unit_conversion()} |
  {:reporter_options, reporter_options()}
```
```

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

### tags()

Source: https://telemetry-metrics.hexdocs.pm/

Represents a list of tags, used for categorizing and filtering telemetry metrics.

```APIDOC
## Type: tags()

### Description
Represents a list of `tag()` types.

### Definition
```elixir
@type tags() :: [tag()]
```
```

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

### tag()

Source: https://telemetry-metrics.hexdocs.pm/

Represents a single tag, which can be any term, used for categorizing metrics.

```APIDOC
## Type: tag()

### Description
Represents a single tag, which can be any term.

### Definition
```elixir
@type tag() :: term()
```
```

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

### summary

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a summary metric. This function is used to define metrics that track statistical summaries of values.

```APIDOC
## summary

### Description
Returns a definition of summary metric.

### Function Signature
summary(metric_name, options \\ [])

### Parameters
#### Path Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (keyword()) - Optional - A list of options for the metric.

### Response
#### Success Response
- Returns a definition of a summary metric.
```

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

### Define a Distribution Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Use this to define a distribution metric that builds a histogram of selected measurement values. The reporter configures the distribution bucket boundaries.

```Elixir
distribution(
  "http.request.duration",
  tags: [:controller, :action]
)
```

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

### Define Telemetry Supervisor Module

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

This module sets up the telemetry poller and metrics reporter as children of a supervisor. It configures periodic measurements and defines the specific metrics to be collected.

```elixir
defmodule MyAppWeb.Telemetry do
  use Supervisor
  import Telemetry.Metrics

  def start_link(arg) do
    Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
  end

  def init(_arg) do
    children = [
      {:telemetry_poller,
       measurements: periodic_measurements(),
       period: 10_000},
      # Or TelemetryMetricsPrometheus or TelemetryMetricsFooBar
      {TelemetryMetricsStatsd, metrics: metrics()}
    ]

    Supervisor.init(children, strategy: :one_for_one)
  end

  defp metrics do
    [
      # VM Metrics
      last_value("vm.memory.total", unit: :byte),
      last_value("vm.total_run_queue_lengths.total"),
      last_value("vm.total_run_queue_lengths.cpu"),
      last_value("vm.total_run_queue_lengths.io"),

      last_value("my_app.worker.memory", unit: :byte),
      last_value("my_app.worker.message_queue_len"),

      # Database Time Metrics
      summary("my_app.repo.query.total_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.decode_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.query_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.idle_time", unit: {:native, :millisecond}),
      summary("my_app.repo.query.queue_time", unit: {:native, :millisecond}),

      # Phoenix Time Metrics
      summary("phoenix.endpoint.stop.duration",
              unit: {:native, :millisecond}),
      summary(
        "phoenix.router_dispatch.stop.duration",
        unit: {:native, :millisecond},
        tags: [:plug]
      )
    ]
  end

  defp periodic_measurements do
    [
      {:process_info,
       event: [:my_app, :worker],
       name: Rumbl.Worker,
       keys: [:message_queue_len, :memory]}
    ]
  end
end
```

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

### counter/2

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition of a counter metric. This metric keeps track of the total number of specific events emitted, incrementing by one for each accounted event.

```APIDOC
## counter/2

### Description
Returns a definition of counter metric. Counter metric keeps track of the total number of specific events emitted. The value of the counter is always incremented by one, regardless of the value of the measurement. However, note the measurement must still be available in the event, otherwise the event is not accounted for.

### Function Signature
```elixir
counter(metric_name :: String.t(), options :: keyword()) :: Telemetry.Metrics.Counter.t()
```

### Parameters
#### Keyword Parameters
- **metric_name** (String.t()) - The name of the metric.
- **options** (keyword()) - A list of options for the metric. Common options include `:tags` (list of atoms) and `:description` (String.t()).

### Example
```elixir
counter("http.request.count", tags: [:controller, :action])
```
```

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

### Group Metrics by Event Name

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Groups a list of metrics by their event names, useful for attaching a single handler to multiple metrics.

```Elixir
Enum.group_by(metrics, & &1.event_name)
```

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

### sum(metric_name, options)

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition of a sum metric. This metric keeps track of the sum of selected measurement's values carried by specific events.

```APIDOC
## sum(metric_name, options)

### Description
Returns a definition of a sum metric. Sum metric keeps track of the sum of selected measurement's values carried by specific events.

### Function Signature
```elixir
sum(metric_name(), metric_options()) :: Telemetry.Metrics.Sum.t()
```

### Example
```elixir
sum("user.session_count", event_name: "user.session_count", measurement: :delta, tags: [:role])
```
```

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

### distribution/2

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition of a distribution metric. This metric builds a histogram of selected measurement's values, allowing for analysis of value distribution.

```APIDOC
## distribution/2

### Description
Returns a definition of distribution metric. Distribution metric builds a histogram of selected measurement's values. It is up to the reporter to decide how the boundaries of the distribution buckets are configured.

### Function Signature
```elixir
distribution(metric_name :: String.t(), options :: keyword()) :: Telemetry.Metrics.Distribution.t()
```

### Parameters
#### Keyword Parameters
- **metric_name** (String.t()) - The name of the metric.
- **options** (keyword()) - A list of options for the metric. Common options include `:tags` (list of atoms) and `:description` (String.t()).

### Example
```elixir
distribution("http.request.duration", tags: [:controller, :action])
```
```

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

### Define a Counter Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Use this to define a counter metric that tracks the total number of specific events. The measurement must be present in the event for it to be accounted for.

```Elixir
counter(
  "http.request.count",
  tags: [:controller, :action]
)
```

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

### time_unit_conversion()

Source: https://telemetry-metrics.hexdocs.pm/

Specifies a conversion between two time units, useful for standardizing time measurements.

```APIDOC
## Type: time_unit_conversion()

### Description
Specifies a conversion between two `time_unit()` types.

### Definition
```elixir
@type time_unit_conversion() :: {time_unit(), time_unit()}
```
```

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

### Emit Telemetry Events with Tag Metadata

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Emit Telemetry events for database queries, including the 'table' and 'operation' metadata required for tagging the 'db.query.duration' counter.

```elixir
:telemetry.execute([:db, :query], %{duration: 198}, %{table: "users", operation: "insert"})
:telemetry.execute([:db, :query], %{duration: 112}, %{table: "users", operation: "select"})
:telemetry.execute([:db, :query], %{duration: 201}, %{table: "sessions", operation: "insert"})
:telemetry.execute([:db, :query], %{duration: 212}, %{table: "sessions", operation: "insert"})
```

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

### sum/2

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a sum metric. This metric keeps track of the sum of selected measurement's values carried by specific events.

```APIDOC
## sum/2

### Description
Returns a definition of sum metric. Sum metric keeps track of the sum of selected measurement's values carried by specific events.

### Function Signature
`sum(metric_name(), metric_options()) :: Telemetry.Metrics.Sum.t()`

### Parameters
- `metric_name`: The name of the metric.
- `options`: A map of options for the metric, such as `event_name`, `measurement`, and `tags`.

### Example
```
sum(
  "user.session_count",
  event_name: "user.session_count",
  measurement: :delta,
  tags: [:role]
)
```
```

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

### Telemetry.Metrics.Sum Type Specification

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.Sum.html

Defines the structure of a %Telemetry.Metrics.Sum{} struct, used for specifying sum metrics. This includes fields for description, event name, metric name, tags, units, and reporter options.

```Elixir
@type t() :: %Telemetry.Metrics.Sum{
  description: Telemetry.Metrics.description(),
  event_name: :telemetry.event_name(),
  keep: Telemetry.Metrics.keep(),
  measurement: Telemetry.Metrics.measurement(),
  name: Telemetry.Metrics.normalized_metric_name(),
  reporter_options: Telemetry.Metrics.reporter_options(),
  tag_values: Telemetry.Metrics.tag_values(),
  tags: Telemetry.Metrics.tags(),
  unit: Telemetry.Metrics.unit()
}
```

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

### t()

Source: https://telemetry-metrics.hexdocs.pm/

Represents the base types for different kinds of telemetry metrics, such as Counter, LastValue, Sum, Summary, and Distribution.

```APIDOC
## Type: t()

### Description
Represents one of the base metric definitions available in Telemetry Metrics.

### Definition
```elixir
@type t() ::
  Telemetry.Metrics.Counter.t() |
  Telemetry.Metrics.LastValue.t() |
  Telemetry.Metrics.Sum.t() |
  Telemetry.Metrics.Summary.t() |
  Telemetry.Metrics.Distribution.t()
```
```

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

### Attach Event Handler for Metrics

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Attaches a telemetry event handler for a group of metrics associated with a specific event name. The handler function `handle_event/4` is called for each event.

```Elixir
for {event, metrics} <- Enum.group_by(metrics, & &1.event_name) do
  id = {__MODULE__, event, self()}
  :telemetry.attach(id, event, &handle_event/4, metrics)
end
```

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

### Distribution Metric Type Specification

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.Distribution.html

Defines the structure of a distribution metric, including its name, description, unit, and associated tags.

```elixir
@type t() :: %Telemetry.Metrics.Distribution{
  description: Telemetry.Metrics.description(),
  event_name: :telemetry.event_name(),
  keep: Telemetry.Metrics.keep(),
  measurement: Telemetry.Metrics.measurement(),
  name: Telemetry.Metrics.normalized_metric_name(),
  reporter_options: Telemetry.Metrics.reporter_options(),
  tag_values: Telemetry.Metrics.tag_values(),
  tags: Telemetry.Metrics.tags(),
  unit: Telemetry.Metrics.unit()
}
```

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

### Define a Sum Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a sum metric. Use this to track the sum of measurement values carried by specific events. Requires event name, measurement type, and optional tags.

```Elixir
@spec sum(metric_name(), metric_options()) :: Telemetry.Metrics.Sum.t()
```

```Elixir
sum(
  "user.session_count",
  event_name: "user.session_count",
  measurement: :delta,
  tags: [:role]
)
```

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

### Filter Metrics Based on Metadata

Source: https://telemetry-metrics.hexdocs.pm/

Use `:drop` to exclude events matching specific metadata, like a `:fast_client` name, from a general metric. Use `:keep` to include only events matching specific metadata for a specialized metric.

```elixir
distribution(
  "http.client.request.duration",
  event_name: [:http_client, :request, :stop],
  drop: &(match?(%{name: :fast_client}, &1))
)

distribution(
  "http.fast.client.request.duration",
  event_name: [:http_client, :request, :stop],
  keep: &(match?(%{name: :fast_client}, &1))
)
```

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

### Add Telemetry Poller Dependency

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Add the :telemetry_poller package as a dependency to your project to access VM metrics and custom periodic measurements.

```elixir
{:telemetry_poller, "~> 0.4"}
```

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

### Define Metrics for Console Reporter

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.ConsoleReporter.html

Defines a list of metrics to be reported by the ConsoleReporter. These include last_value and counter types with specified units.

```elixir
metrics = [
  last_value("vm.memory.binary", unit: :byte),
  counter("vm.memory.total")
]
```

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

### Configure Telemetry Poller Period

Source: https://telemetry-metrics.hexdocs.pm/

Set the measurement frequency for `telemetry_poller` in your configuration file. The default period is 5000 milliseconds.

```elixir
config :telemetry_poller, :default, period: 5_000
```

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

### distribution

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a distribution metric. This function is used to define metrics that track the distribution of values.

```APIDOC
## distribution

### Description
Returns a definition of distribution metric.

### Function Signature
distribution(metric_name, options \\ [])

### Parameters
#### Path Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (keyword()) - Optional - A list of options for the metric.

### Response
#### Success Response
- Returns a definition of a distribution metric.
```

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

### Counter Type Specification

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.Counter.html

Defines the structure of a counter metric, including its description, event name, measurement, tags, and unit.

```elixir
@type t() :: %Telemetry.Metrics.Counter{
  description: Telemetry.Metrics.description(),
  event_name: :telemetry.event_name(),
  keep: Telemetry.Metrics.keep(),
  measurement: Telemetry.Metrics.measurement(),
  name: Telemetry.Metrics.normalized_metric_name(),
  reporter_options: Telemetry.Metrics.reporter_options(),
  tag_values: Telemetry.Metrics.tag_values(),
  tags: Telemetry.Metrics.tags(),
  unit: Telemetry.Metrics.unit()
}
```

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

### Summary Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a summary metric. This metric type can be used to track various statistical measures like count, sum, min, and max.

```APIDOC
## summary(metric_name, options \\ [])

### Description
Returns a definition of summary metric.

### Method
Not Applicable (Function Call)

### Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (Keyword.t()) - Optional - Additional options for the metric definition.
```

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

### Define Byte Unit Conversion Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Defines a tuple for converting between two byte units.

```Elixir
@type byte_unit_conversion() :: {byte_unit(), byte_unit()}
```

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

### Distribution Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a distribution metric. This metric type is useful for tracking the statistical distribution of a set of values.

```APIDOC
## distribution(metric_name, options \\ [])

### Description
Returns a definition of distribution metric.

### Method
Not Applicable (Function Call)

### Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (Keyword.t()) - Optional - Additional options for the metric definition.
```

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

### counter

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a counter metric. This function is used to define a metric that counts occurrences.

```APIDOC
## counter

### Description
Returns a definition of counter metric.

### Function Signature
counter(metric_name, options \\ [])

### Parameters
#### Path Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (keyword()) - Optional - A list of options for the metric.

### Response
#### Success Response
- Returns a definition of a counter metric.
```

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

### Counter Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a counter metric. This metric type is suitable for tracking cumulative counts.

```APIDOC
## counter(metric_name, options \\ [])

### Description
Returns a definition of counter metric.

### Method
Not Applicable (Function Call)

### Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (Keyword.t()) - Optional - Additional options for the metric definition.
```

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

### Configure Telemetry Poller Period

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Change the measurement frequency of telemetry poller metrics by setting the :period configuration. Set to false to disable.

```elixir
config :telemetry_poller, :default, period: 5_000
```

```elixir
config :telemetry_poller, :default, false
```

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

### Define Byte Unit Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies the possible units for byte measurements.

```Elixir
@type byte_unit() :: :megabyte | :kilobyte | :byte
```

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

### LastValue Metric Specification

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.LastValue.html

Defines the structure of a LastValue metric, including fields for description, event name, measurement, tags, and reporter options.

```Elixir
@type t() :: %Telemetry.Metrics.LastValue{
  description: Telemetry.Metrics.description(),
  event_name: :telemetry.event_name(),
  keep: Telemetry.Metrics.keep(),
  measurement: Telemetry.Metrics.measurement(),
  name: Telemetry.Metrics.normalized_metric_name(),
  reporter_options: Telemetry.Metrics.reporter_options(),
  tag_values: Telemetry.Metrics.tag_values(),
  tags: Telemetry.Metrics.tags(),
  unit: Telemetry.Metrics.unit()
}
```

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

### sum

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a sum metric. This function is used to define metrics that track the cumulative sum of values.

```APIDOC
## sum

### Description
Returns a definition of sum metric.

### Function Signature
sum(metric_name, options \\ [])

### Parameters
#### Path Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (keyword()) - Optional - A list of options for the metric.

### Response
#### Success Response
- Returns a definition of a sum metric.
```

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

### Summary Metric Type Specification

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.Summary.html

Defines the structure of a summary metric, including its name, description, measurement, and associated tags. This type is used to configure how summary metrics are reported.

```Elixir
@type t() :: %Telemetry.Metrics.Summary{
  description: Telemetry.Metrics.description(),
  event_name: :telemetry.event_name(),
  keep: Telemetry.Metrics.keep(),
  measurement: Telemetry.Metrics.measurement(),
  name: Telemetry.Metrics.normalized_metric_name(),
  reporter_options: Telemetry.Metrics.reporter_options(),
  tag_values: Telemetry.Metrics.tag_values(),
  tags: Telemetry.Metrics.tags(),
  unit: Telemetry.Metrics.unit()
}
```

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

### Define a Last Value Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Use this to define a last value metric that tracks the measurement from the most recent event. Ensure the measurement is available in the event.

```Elixir
last_value(
  "vm.memory.total",
  description: "Total amount of memory allocated by the Erlang VM", unit: :byte
)
```

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

### Define Time Unit Conversion

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Represents a conversion between two time units. Use this to specify how time measurements should be scaled.

```elixir
@type time_unit_conversion() :: {time_unit(), time_unit()}
```

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

### predicate_fun()

Source: https://telemetry-metrics.hexdocs.pm/

A function used to determine if a metric should be processed based on event metadata and measurements.

```APIDOC
## Type: predicate_fun()

### Description
A function that takes telemetry event metadata and optionally measurements to return a boolean indicating whether to process the metric.

### Definition
```elixir
@type predicate_fun() ::
  (:telemetry.event_metadata() -> boolean()) |
  (:telemetry.event_metadata(), :telemetry.event_measurements() -> boolean())
```
```

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

### Sum Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a sum metric. This metric type is used to track the total sum of reported values.

```APIDOC
## sum(metric_name, options \\ [])

### Description
Returns a definition of sum metric.

### Method
Not Applicable (Function Call)

### Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (Keyword.t()) - Optional - Additional options for the metric definition.
```

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

### Define Measurement Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies the possible types for event measurements.

```Elixir
@type measurement() ::
  term()
  | (:telemetry.event_measurements() -> number())
  | (:telemetry.event_measurements(), :telemetry.event_metadata() -> number())
```

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

### Define Time Unit

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies the unit of time for measurements. Supports second, millisecond, microsecond, nanosecond, and native units.

```elixir
@type time_unit() :: :second | :millisecond | :microsecond | :nanosecond | :native
```

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

### Elixir Reporter keep?/2 Function

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Determines if a metric should be recorded based on a provided 'keep' function in the metric's configuration. If no 'keep' function is defined, it defaults to keeping the metric.

```Elixir
defp keep?(%{keep: keep}, metadata) when keep != nil, do: keep.(metadata)
defp keep?(_metric, _metadata), do: true
```

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

### Define Counter Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Defines a counter metric to count the total number of times a specific Telemetry event occurs. The metric name is derived from the event.

```elixir
Telemetry.Metrics.counter("http.request.stop.duration")
```

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

### Define Tag Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Represents a single tag, which can be any term. Tags are used to categorize and filter metrics.

```elixir
@type tag() :: term()
```

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

### Define Summary Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Defines a summary metric to calculate statistics (like mean, percentiles) about a specific measurement within Telemetry events. The metric name is derived from the event.

```elixir
Telemetry.Metrics.summary("http.request.stop.duration")
```

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

### Elixir Reporter extract_measurement/2 Function

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Extracts a measurement value for a given metric from the event's measurements. It supports fetching measurements by a key or by calling a function defined in the metric's configuration.

```Elixir
def extract_measurement(metric, measurements) do
  case metric.measurement do
    fun when is_function(fun, 1) -> fun.(measurements)
    key -> measurements[key]
  end
end
```

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

### last_value/2

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition of a last value metric. This metric keeps track of the measurement's value from the most recent event.

```APIDOC
## last_value/2

### Description
Returns a definition of last value metric. Last value keeps track of the selected measurement found in the most recent event.

### Function Signature
```elixir
last_value(metric_name :: String.t(), options :: keyword()) :: Telemetry.Metrics.LastValue.t()
```

### Parameters
#### Keyword Parameters
- **metric_name** (String.t()) - The name of the metric.
- **options** (keyword()) - A list of options for the metric. Common options include `:tags` (list of atoms), `:description` (String.t()), and `:unit` (atom()).

### Example
```elixir
last_value("vm.memory.total", description: "Total amount of memory allocated by the Erlang VM", unit: :byte)
```
```

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

### Generate Unique Handler ID

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Generates a unique identifier for an event handler, combining reporter name, event name, and process ID.

```Elixir
id = {PigeonReporter, metric.event_name, self()}
```

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

### last_value

Source: https://telemetry-metrics.hexdocs.pm/

Returns a definition of a last value metric. This function is used to define metrics that track the last observed value.

```APIDOC
## last_value

### Description
Returns a definition of last value metric.

### Function Signature
last_value(metric_name, options \\ [])

### Parameters
#### Path Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (keyword()) - Optional - A list of options for the metric.

### Response
#### Success Response
- Returns a definition of a last value metric.
```

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

### Define Metric Name Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Specifies that a metric name can be a string or a normalized metric name (list of atoms).

```Elixir
@type metric_name() :: String.t() | normalized_metric_name()
```

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

### Define Predicate Function

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Defines a function used to filter telemetry events based on their metadata and measurements. It can take event metadata alone or both metadata and measurements as arguments.

```elixir
@type predicate_fun() ::
  (:telemetry.event_metadata() -> boolean())
  | (:telemetry.event_metadata(), :telemetry.event_measurements() -> boolean())
```

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

### Define Base Metric Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Represents one of the fundamental metric types available in the Telemetry.Metrics library. Choose the appropriate type based on the data you are collecting.

```elixir
@type t() ::
  Telemetry.Metrics.Counter.t()
  | Telemetry.Metrics.LastValue.t()
  | Telemetry.Metrics.Sum.t()
  | Telemetry.Metrics.Summary.t()
  | Telemetry.Metrics.Distribution.t()
```

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

### Define Normalized Metric Name

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Represents the name of a metric as a list of atoms. This format is used internally for consistent metric identification.

```elixir
@type normalized_metric_name() :: [atom(), ...]
```

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

### Last Value Metric

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Returns a definition for a last value metric. This metric type tracks the most recent value reported for a given metric.

```APIDOC
## last_value(metric_name, options \\ [])

### Description
Returns a definition of last value metric.

### Method
Not Applicable (Function Call)

### Parameters
- **metric_name** (String.t() | normalized_metric_name()) - Required - The name of the metric.
- **options** (Keyword.t()) - Optional - Additional options for the metric definition.
```

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

### Elixir Reporter extract_tags/2 Function

Source: https://telemetry-metrics.hexdocs.pm/writing_reporters.html

Extracts and filters tags for a metric from event metadata. It first applies a transformation to the metadata using a `:tag_values` function and then selects only the tags specified in the metric's configuration.

```Elixir
def extract_tags(metric, metadata) do
  tag_values = metric.tag_values.(metadata)
  Map.take(tag_values, metric.tags)
end
```

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

### Define Tag Values Function

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

A function that transforms event metadata, typically used for generating or modifying tag values associated with a metric.

```elixir
@type tag_values() :: (:telemetry.event_metadata() -> :telemetry.event_metadata())
```

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

### Define Drop Predicate Function Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Defines the type for a predicate function used for dropping telemetry events.

```Elixir
@type drop() :: predicate_fun()
```

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

### Disable Telemetry Poller

Source: https://telemetry-metrics.hexdocs.pm/

Completely disable the `telemetry_poller` by setting its configuration to `false`.

```elixir
config :telemetry_poller, :default, false
```

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

### tag_values()

Source: https://telemetry-metrics.hexdocs.pm/

A function that transforms event metadata, likely used for filtering or modifying tag values associated with metrics.

```APIDOC
## Type: tag_values()

### Description
A function that takes event metadata and returns event metadata, often used for processing tag values.

### Definition
```elixir
@type tag_values() :: (:telemetry.event_metadata() -> :telemetry.event_metadata())
```
```

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

### normalized_metric_name()

Source: https://telemetry-metrics.hexdocs.pm/

The name of a metric represented as a list of atoms, providing a structured way to identify metrics.

```APIDOC
## Type: normalized_metric_name()

### Description
The name of the metric represented as a list of atoms.

### Definition
```elixir
@type normalized_metric_name() :: [atom(), ...]
```
```

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

### Define Keep Predicate Function Type

Source: https://telemetry-metrics.hexdocs.pm/Telemetry.Metrics.html

Defines the type for a predicate function used for keeping telemetry events.

```Elixir
@type keep() :: predicate_fun()
```
Tokens:
Raw