Skip to content

Commit 6d1e2a8

Browse files
ZPain8464ZPain8464
authored
Move Enterprise metrics content (#1621)
* creates configure-metrics file * migrates content to guides * updates prometheus guide * updates screenshots * runs prettier * fixes typo * Update content/docs/guides/configure-metrics.mdx * Update content/docs/guides/configure-metrics.mdx * Update content/docs/guides/configure-metrics.mdx * updates sections * moves guide and adds external and embedded definitions * updates formatting * changes 'web console' to 'Enterprise Console'
1 parent 41470ad commit 6d1e2a8

File tree

4 files changed

+125
-0
lines changed

4 files changed

+125
-0
lines changed

‎content/docs/enterprise/configure-metrics.mdx

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
# cSpell:ignore XPOST tsdb
3+
4+
title: Configure Metrics in Pomerium Enterprise
5+
sidebar_label: Metrics
6+
description: Learn how to configure Prometheus to power metrics in the Pomerium Enterprise Console.
7+
lang: en-US
8+
keywords: [pomerium, enterprise pomerium, telemetry, metrics, prometheus]
9+
---
10+
11+
Learn how to configure [Prometheus](https://prometheus.io/) as a metrics collection backend in Pomerium Enterprise.
12+
13+
## Overview
14+
15+
Pomerium Enterprise uses Prometheus to collect observability and monitoring metrics from your Pomerium deployment. To set up Pomerium to work with Prometheus, you must configure either an external or embedded Prometheus instance.
16+
17+
This guide explains what the [external](#external-prometheus) and [embedded](#embedded-prometheus) Prometheus options are, and how to configure them.
18+
19+
## Before you start
20+
21+
To complete this guide, you need:
22+
23+
- [Pomerium Enterprise](/docs/enterprise)
24+
- [Pomerium Core](/docs/core)
25+
26+
This guide runs both Pomerium instances on localhost (`127.0.0.1`).
27+
28+
## Configure Pomerium
29+
30+
In your Pomerium Enterprise configuration file, define the `metrics_addr` key to a network interface or port:
31+
32+
```yaml title="pomerium-enterprise.yaml"
33+
metrics_addr: 127.0.0.1:9092
34+
```
35+
36+
This setting exposes internal metrics within the Enterprise Console. If not defined, Pomerium will expose `127.0.0.1` on port `:9092` by default.
37+
38+
## Configure Prometheus
39+
40+
### External Prometheus
41+
42+
An external Prometheus instance runs as its own process separate from Pomerium. Use this option if you prefer to configure and maintain Prometheus yourself.
43+
44+
The steps below show you how to connect Prometheus to Pomerium Core and Pomerium Enterprise.
45+
46+
:::tip
47+
48+
For production deployments, we suggest using a dedicated Prometheus instance.
49+
50+
:::
51+
52+
1. In your Prometheus configuration file, add [instances](https://prometheus.io/docs/concepts/jobs_instances/#jobs-and-instances) for Pomerium and Pomerium Enterprise:
53+
54+
```yaml title="prometheus.yaml"
55+
- job_name: 'Pomerium'
56+
scrape_interval: 30s
57+
scrape_timeout: 5s
58+
static_configs:
59+
- targets: ['127.0.0.1:9091']
60+
- job_name: 'Pomerium Enterprise'
61+
scrape_interval: 30s
62+
scrape_timeout: 5s
63+
static_configs:
64+
- targets: ['127.0.0.1:9092']
65+
66+
```
67+
68+
1. [Reload](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration) the Prometheus configuration:
69+
70+
```bash
71+
curl -i -XPOST path.to.prometheus:port/-/reload
72+
```
73+
74+
1. In your Pomerium Enterprise configuration file, define the [`prometheus_url`](/docs/enterprise/configure#prometheus-url) key to point to your Prometheus instance. The example below uses port 9090, the default [Prometheus port](https://prometheus.io/docs/introduction/first_steps/).
75+
76+
```yaml title="pomerium-enterprise.yaml"
77+
prometheus_url: http://192.168.122.50:9090
78+
```
79+
80+
1. In your Pomerium configuration file, define the [`metrics_address`](/docs/reference/metrics#metrics-address) key to a network interface or port. In the example below, Pomerium provides metrics at port `9091` on an IP address reachable by Pomerium Enterprise:
81+
82+
```yaml title="pomerium.yaml"
83+
metrics_address: 127.0.0.1:9091
84+
```
85+
86+
:::note
87+
88+
If you're running Pomerium Enterprise in a distributed environment where the IP address is unknown at the time of deployment, you can use the resolvable fully qualified domain name (FQDN) of the Pomerium host (for example, `pomerium0.internal.example.com`). Or, you can override this key with the [`METRICS_ADDRESS`](/docs/reference/metrics#metrics-address) environment variable.
89+
90+
We do not recommend exposing this endpoint to public traffic as it can contain potentially sensitive information.
91+
92+
:::
93+
94+
### Embedded Prometheus
95+
96+
Pomerium Enterprise supports an embedded Prometheus instance that you configure only in Pomerium. Use this option if you don't want to maintain an external Prometheus instance, or if you're testing metrics.
97+
98+
To configure an embedded Prometheus instance, add the [`prometheus_data_dir`](/docs/enterprise/configure#prometheus-data-dir) key and file path in your Pomerium Enterprise configuration file:
99+
100+
```yaml title="pomerium-enterprise.yaml"
101+
prometheus_data_dir: /var/lib/pomerium-console/tsdb
102+
```
103+
104+
:::note
105+
106+
The directory path can be any location that you have permissions to write to. This example uses the default location created if you install Pomerium Enterprise with the [OS Packages](/docs/enterprise/install#install-pomerium-enterprise) option.
107+
108+
:::
109+
110+
## Test the configuration
111+
112+
To view metrics collected by Prometheus, you must restart the Pomerium and Pomerium Enterprise services.
113+
114+
In the Enterprise Console, select **Traffic**. You should see route traffic metrics collected from your Pomerium deployment:
115+
116+
![Traffic Data in Pomerium Enterprise](./img/metrics/traffic-dashboard.png)
117+
118+
To view monitoring metrics for an external data source:
119+
120+
1. Select **External Data**.
121+
1. Select an external data source.
122+
1. Select the **Metrics** tab. You should see monitoring data collected from the external data source record:
123+
124+
![External Data Source in Pomerium Enterprise](./img/metrics/external-data-sources-dashboard.png)

‎content/docs/enterprise/img/metrics/external-data-sources-dashboard.png

46.8 KB
Loading

‎content/docs/enterprise/img/metrics/traffic-dashboard.png

59.2 KB
Loading

‎sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ const sidebars = {
5959
'docs/enterprise/quickstart',
6060
'docs/enterprise/install',
6161
'docs/enterprise/configure',
62+
'docs/enterprise/configure-metrics',
6263
'docs/enterprise/changelog',
6364
'docs/enterprise/upgrading',
6465
],

0 commit comments

Comments
 (0)