PromEx.Config (PromEx v0.1.7-alpha) View Source
This module defines a struct that contains all of the fields necessary to configure an instance of PromEx.
While this module does not directly access your Application config, PromEx will call the
PromEx.Config.build/1
function directly with the contents of Application.get_env(:your_otp_app, YourPromEx.Module)
. As
such, this is an appropriate place to talk about how you go about configuring PromEx via your Application config.
By default, you can run PromEx without any additional configuration and PromEx will fall back on some sane defaults. Specifically, if you were to not add any configuration to your config.exs, dev.exs, prod.exs, etc files it would be the same as setting the following config:
config :web_app, WebApp.PromExs,
manual_metrics_start_delay: :no_delay,
drop_metrics_groups: [],
grafana: :disabled,
metrics_server: :disabled
In this configuration, the Grafana dashboards are not uploaded on application start, and a standalone HTTP metrics server is not started. In addition, the ManualMetricsManager is started without any time delay, and all metrics groups from all the plugins are regestered and set up.
If you would like to set up PromEx to communicate with Grafana, your config would look something like:
config :web_app, WebApp.PromExs,
grafana: [
host: "http://localhost:3000",
auth_token: "<YOUR_AUTH_TOKEN_HERE>",
datasource_id: "<YOUR_DATASOURCE_ID_HERE>",
upload_dashboards_on_start: true # This is an optional setting and will default to `true`
]
If you would like PromEx to start a standalone HTTP server to serve your aggregated metrics, you can leverage the :metrics_server
config:
config :web_app, WebApp.PromExs,
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 `[]`
]
Option Details
:manual_metrics_start_delay
- Manual metrics are gathered once on start up and then only when you callPromEx.ManualMetricsManager.refresh_metrics/1
. Sometimes, you may have metrics that require your entire supervision tree to be started in order to fetch accurate data. This option will allow you to delays the initial metrics capture of theManualMetricsManager
by a certain number of milliseconds or the:no_delay
atom if you want the metrics to be captured as soon as theManualMetricsManager
starts up. Default value::no_delay
:drop_metrics_groups
- A list of all the metrics groups that you are not interested in tracking. For example, if your application does not leverage Phoenix channels at all but you still would like to use thePromEx.Plugins.Phoenix
plugin, you can pass [:phoenix_channel_event_metrics
] as the value to:drop_metrics_groups
and that set of metrics will not be caputred. Default value:[]
:grafana
- This key contains the configuration information for connecting to Grafana. Its configuration options are::host
- The host address of your Grafana instance. In order for PromEx to communicate with Grafana this valueshould be in the formatprotocol://host:port
likehttp://localhost:3000
for example.:auth_token
- The auth token that was created in Grafana so that PromEx can upload dashboards via the API.:datasource_id
- When configuring a datasource in Grafana, you allocate an ID to each datasource. This datasource is required by the queries that populate the graphs so that Grafana knows what backing time-series data store to communicate with. Given that PromEx works with Prometheus, you'll need to tell PromEx what the ID of the Prometheus datasource is in Grafana. This value is required so that the PromQL queries can be directed to the correct Prometheus instance.:upload_dashboards_on_start
- Using the config values that you set in your application config (config.exs
,dev.exs
,prod.exs
, etc) PromEx will attempt to upload your Dashboards to Grafana using Grafana's HTTP API.
:metrics_server
- This key contains the configuration information needed to run a standalone HTTP server powered by Cowboy. This server provides a lightweight solution to serving up PromEx metrics. Its configuration options are::port
- The port that the Cowboy HTTP server should run on.:path
- The path that the metrics should be accessible at.:protocol
- The protocol that the metrics should be accessible over (:http
or:https
).:pool_size
- How many Cowboy processes should be in the pool to handle metrics related requests.:cowboy_opts
- A keyword list of any additional options that should be passed toPlug.Cowboy
(see docs for more information https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html). The:port
and:transport_options
options are handled by PromEx via the aforementioned config settings and so adding them again here has no effect.
Link to this section Summary
Types
manual_metrics_start_delay
: How the ManualMetricsManager worker process should be started (instantly or with a millisecond delay).drop_metrics_groups
: A list of metrics groups that should be omitted from the metrics collection process.grafana_config
: A map containing all the relevant settings to connect to Grafana.metrics_server_config
: A map containing all the relevant settings to start a standalone HTTP Cowboy server for metrics.
Functions
Create a struct that encapsulates all of the configuration needed to start a PromEx supervisor instance as well as all of the worker processes.
Link to this section Types
Specs
t() :: %PromEx.Config{ drop_metrics_groups: MapSet.t(), grafana_config: map(), manual_metrics_start_delay: :no_delay | pos_integer(), metrics_server_config: map() }
manual_metrics_start_delay
: How the ManualMetricsManager worker process should be started (instantly or with a millisecond delay).drop_metrics_groups
: A list of metrics groups that should be omitted from the metrics collection process.grafana_config
: A map containing all the relevant settings to connect to Grafana.metrics_server_config
: A map containing all the relevant settings to start a standalone HTTP Cowboy server for metrics.
Link to this section Functions
Specs
Create a struct that encapsulates all of the configuration needed to start a PromEx supervisor instance as well as all of the worker processes.