Merge pull request #18 from authzed/dedicated-metrics-examples

Dedicated metrics examples

authzed-dedicated-metrics/datadog/otel-config.yaml

@@ -0,0 +1,24 @@
+---
+receivers:
+  prometheus:
+    config:
+      scrape_configs:
+        - job_name: "prometheus"
+          metrics_path: "/api/v1alpha/metrics"
+          scrape_interval: "15s"
+          static_configs:
+            - targets: ["<YOUR_AUTHZED_DEDICATED_INSTANCE>"]
+          basic_auth:
+            username: "<PS_NAME>"
+            password: "<METRICS_TOKEN>"
+exporters:
+  datadog:
+    api:
+      site: "<YOUR_DATADOG_SITE>"
+      key: "<YOUR_DATADOG_API_KEY>"
+service:
+  pipelines:
+    metrics:
+      receivers: ["prometheus"]
+      processors: []
+      exporters: ["datadog"]

authzed-dedicated-metrics/datadog/readme.md

@@ -0,0 +1,79 @@
+
+# OpenTelemetry Collector for AuthZed Dedicated Metrics
+
+This guide explains how to deploy the OpenTelemetry Collector Contributor image to collect metrics from AuthZed Dedicated and push them to Datadog.
+
+## Prerequisites
+
+- Docker installed on your machine.
+- Access to AuthZed Dedicated instance.
+- Datadog API key.
+
+## Deployment
+
+### Step 1: Prepare the Configuration File
+
+Create a configuration file named `otel-config.yaml` with the following content. Be sure to replace the placeholders with your actual values:
+
+```yaml
+receivers:
+  prometheus:
+    config:
+      scrape_configs:
+        - job_name: 'prometheus'
+          metrics_path: /api/v1alpha/metrics
+          scrape_interval: 15s
+          static_configs:
+            - targets: ['<YOUR_AUTHZED_DEDICATED_INSTANCE>']
+          basic_auth:
+            username: '<PS_NAME>'
+            password: '<METRICS_TOKEN>'
+
+exporters:
+  datadog:
+    api:
+      site: "<YOUR_DATADOG_SITE>"
+      key: "<YOUR_DATADOG_API_KEY>"
+
+service:
+  pipelines:
+    metrics:
+      receivers: [prometheus]
+      processors: []
+      exporters: [datadog]
+```
+
+### Step 2: Deploy the OpenTelemetry Collector
+
+Run the following Docker command to deploy the OpenTelemetry Collector:
+
+```bash
+docker run --rm -d --name otel-collector -v "$(pwd)/otel-config.yaml:/otel-config.yaml" otel/opentelemetry-collector-contrib:latest --config=/otel-config.yaml
+```
+
+This command will start the OpenTelemetry Collector, which will begin scraping metrics from your AuthZed Dedicated instance and exporting them to Datadog.
+
+### Step 3: Verify the Metrics in Datadog
+
+Log in to your Datadog account and navigate to the metrics section. You should see the metrics from your AuthZed Dedicated instance being reported.
+
+## Configuration Details
+
+- `<YOUR_AUTHZED_DEDICATED_INSTANCE>`: Replace with the URL of your AuthZed Dedicated instance (e.g., `example.app.aws.authzed.net`).
+- `<PS_NAME>` and `<METRICS_TOKEN>`: Replace with the username and password for basic authentication to access your AuthZed metrics endpoint.
+- `<YOUR_DATADOG_SITE>`: Replace with your Datadog site URL (e.g., `us5.datadoghq.com`).
+- `<YOUR_DATADOG_API_KEY>`: Replace with your Datadog API key.
+
+## Troubleshooting
+
+If you encounter issues:
+
+- Ensure that the `otel-config.yaml` file is correctly configured and that all placeholders are replaced with actual values.
+- Check the Docker container logs for any errors:
+
+  ```
+  docker logs otel-collector
+  ```
+
+- Verify that your AuthZed Dedicated instance is accessible and that the credentials are correct.
+- Confirm that your Datadog API key and site are correct.

authzed-dedicated-metrics/otel-collector/env-vars.sh

@@ -0,0 +1,5 @@
+export PROMETHEUS_USERNAME='<permission-system-name>'
+export PROMETHEUS_PASSWORD='<permission-system-token>'
+export OTEL_EXPORTER_OTLP_ENDPOINT="https://<metrics-service-url>:443"
+export OTEL_EXPORTER_OTLP_HEADERS="your-service-key"
+export OTEL_SERVICE_NAME="authzed-<permission-system-name>"

authzed-dedicated-metrics/otel-collector/otel-collector-config.yaml

@@ -0,0 +1,23 @@
+---
+receivers:
+  prometheus:
+    config:
+      scrape_configs:
+        - job_name: "prometheus"
+          metrics_path: "/api/v1alpha/metrics"
+          scrape_interval: "15s"
+          static_configs:
+            - targets: ["app.admin.demo.aws.authzed.net"]
+          basic_auth:
+            username: ${PROMETHEUS_USERNAME}  # yamllint disable-line rule:quoted-strings
+            password: ${PROMETHEUS_PASSWORD}  # yamllint disable-line rule:quoted-strings
+exporters:
+  otlp:
+    endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT}  # yamllint disable-line rule:quoted-strings
+    headers:
+      x-honeycomb-team: ${OTEL_EXPORTER_OTLP_HEADERS}  # yamllint disable-line rule:quoted-strings
+service:
+  pipelines:
+    metrics:
+      receivers: ["prometheus"]
+      exporters: ["otlp"]

authzed-dedicated-metrics/otel-collector/readme.md

@@ -0,0 +1,58 @@
+
+# OpenTelemetry Collector - AuthZed Dedicated
+
+This repository provides a simple setup for running the OpenTelemetry Collector in a Docker container, configured to scrape metrics from a Prometheus endpoint and export to a metrics collection service. 
+
+## Prerequisites
+
+- Docker installed on your machine
+- A Prometheus endpoint with valid credentials
+- A metrics service account and API key
+
+## Setup
+
+
+2. **Create the `env-vars.sh` File**
+
+   Edit the file named `env-vars.sh` in the root of the repository with the following content:
+
+   ```sh
+   export PROMETHEUS_USERNAME='<permission-system-name>'
+   export PROMETHEUS_PASSWORD='<permission-system-token>'
+   export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-metrics-service-url"
+   export OTEL_EXPORTER_OTLP_HEADERS="your-service-key"
+   export OTEL_SERVICE_NAME="authzed-<permission-system-name>"
+   ```
+
+   Replace the placeholder values with your actual credentials and configurations.
+
+3. **Create the Configuration File**
+
+   Edit the file named `otel-collector-config.yaml` in the root of the repository.
+
+4. **Make the Script Executable**
+
+   Make the `run-otel-collector.sh` script executable:
+
+   ```bash
+   chmod +x run-otel-collector.sh
+   ```
+
+5. **Run the Script**
+
+   Run the script to start the OpenTelemetry Collector Docker container with the configured settings:
+
+   ```bash
+   ./run-otel-collector.sh
+   ```
+
+## Files
+
+- `env-vars.sh`: Contains the environment variables for Prometheus and Honeycomb configuration.
+- `otel-collector-config.yaml`: Configuration file for the OpenTelemetry Collector.
+- `run-otel-collector.sh`: Shell script to load environment variables and run the OpenTelemetry Collector Docker container.
+
+
+## Contact
+
+If you have any questions or need further assistance, feel free to open an issue or contact support@authzed.com

authzed-dedicated-metrics/otel-collector/run-otel-collector.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Load environment variables from file
+source ./env-vars.sh
+
+# Check if all necessary environment variables are set
+if [[ -z "$PROMETHEUS_USERNAME" || -z "$PROMETHEUS_PASSWORD" || -z "$OTEL_EXPORTER_OTLP_ENDPOINT" || -z "$OTEL_EXPORTER_OTLP_HEADERS" || -z "$OTEL_SERVICE_NAME" ]]; then
+  echo "One or more environment variables are not set. Please check your env-vars.sh file."
+  exit 1
+fi
+
+# Run OpenTelemetry Collector Docker container
+docker run --rm -it \
+  -v $(pwd)/otel-collector-config.yaml:/otel-collector-config.yaml \
+  -e PROMETHEUS_USERNAME="$PROMETHEUS_USERNAME" \
+  -e PROMETHEUS_PASSWORD="$PROMETHEUS_PASSWORD" \
+  -e OTEL_EXPORTER_OTLP_ENDPOINT="$OTEL_EXPORTER_OTLP_ENDPOINT" \
+  -e OTEL_EXPORTER_OTLP_HEADERS="$OTEL_EXPORTER_OTLP_HEADERS" \
+  -e OTEL_SERVICE_NAME="$OTEL_SERVICE_NAME" \
+  otel/opentelemetry-collector:latest \
+  --config otel-collector-config.yaml

authzed-dedicated-metrics/prometheus-grafana/README.md

@@ -0,0 +1,64 @@
+### AuthZed Dedicated - Prometheus & Grafana
+
+## Configuring Prometheus to Scrape Metrics from AuthZed Dedicated 
+
+To enable Prometheus to scrape metrics from your permission system, configure the `scrape_config` section in prometheus.yml. 
+
+1. Open `prometheus.yml` in an editor.
+
+2. Add the following `scrape_config` section to your configuration file, replacing the placeholder values with your specific details:
+
+    ```yaml
+    scrape_configs:
+      - job_name: "exported-metrics-from-[permission-system]"
+        metrics_path: /api/v1alpha/metrics
+        basic_auth:
+          username: "[permission-system]"
+          password: "[token]"
+        static_configs:
+          - targets:
+              - "[authzed-dashboard-url]"
+    ```
+
+### Required Values
+
+- **job_name**: Replace `[permission-system]` with the name of your permission system. This identifies the job in Prometheus.
+  - Example: `job_name: "exported-metrics-from-my-permission-system"`
+
+- **metrics_path**: Set to `/api/v1alpha/metrics`.
+
+- **basic_auth**:
+  - **username**: Replace `[permission-system]` with the permission system name used for basic authentication.
+    - Example: `username: "my-permission-system"`
+  - **password**: Replace `[token]` with the token for basic authentication.
+    - Example: `password: "doGXlyJdtjZHOdCw486t"`
+
+- **static_configs**:
+  - **targets**: Replace `[authzed-dashboard-url]` with the URL of your Authzed dashboard.
+
+    - Example: `targets: ["https://app.demo.aws.authzed.net"]`
+
+### Example Configuration
+
+Here's an example of a filled-out configuration:
+
+    ```yaml
+    scrape_configs:
+      - job_name: "exported-metrics-from-my-permission-system"
+        metrics_path: /api/v1alpha/metrics
+        basic_auth:
+          username: "my-permission-system"
+          password: "my-secret-token"
+        static_configs:
+          - targets:
+              - "https://app.demo.aws.authzed.net"
+    ```
+
+3. Save prometheus.yml 
+
+4. Run `docker compose up`
+
+### Ports:
+
+Prometheus: 9090
+Grafana: 3000

authzed-dedicated-metrics/prometheus-grafana/compose.yaml

@@ -0,0 +1,26 @@
+---
+services:
+  prometheus:
+    image: "prom/prometheus:latest"
+    container_name: "prometheus"
+    command:
+      - "--config.file=/etc/prometheus/prometheus.yml"
+    ports:
+      - "9090:9090"
+    restart: "unless-stopped"
+    volumes:
+      - "./prometheus:/etc/prometheus"
+      - "prom_data:/prometheus"
+  grafana:
+    image: "grafana/grafana:latest"
+    container_name: "grafana"
+    ports:
+      - "3000:3000"
+    restart: "unless-stopped"
+    environment:
+      - "GF_SECURITY_ADMIN_USER=admin"
+      - "GF_SECURITY_ADMIN_PASSWORD=grafana"
+    volumes:
+      - "./grafana:/etc/grafana/provisioning/datasources"
+volumes:
+  prom_data:

authzed-dedicated-metrics/prometheus-grafana/grafana/datasource.yml

@@ -0,0 +1,9 @@
+---
+apiVersion: "1"
+datasources:
+  - name: "Prometheus"
+    type: "prometheus"
+    url: "http://prometheus:9090"
+    isDefault: true
+    access: "proxy"
+    editable: true

authzed-dedicated-metrics/prometheus-grafana/prometheus/prometheus.yml

@@ -0,0 +1,27 @@
+---
+global:
+  scrape_interval: "15s"
+  scrape_timeout: "10s"
+  evaluation_interval: "15s"
+alerting:
+  alertmanagers:
+    - static_configs:
+        - targets: []
+scrape_configs:
+  - job_name: "prometheus"
+    honor_timestamps: true
+    scrape_interval: "15s"
+    scrape_timeout: "10s"
+    metrics_path: "/metrics"
+    scheme: "http"
+    static_configs:
+      - targets:
+          - "localhost:9090"
+  - job_name: "exported-metrics-from-[permission-system]"
+    metrics_path: "/api/v1alpha/metrics"
+    basic_auth:
+      username: "[permission-system]"
+      password: "[token]"
+    static_configs:
+      - targets:
+          - "[authzed-dashboard-url]"

authzed-dedicated-metrics/readme.md

@@ -0,0 +1,18 @@
+# AuthZed Dedicated Metrics
+
+This collection of examples is designed to help you collect metrics from AuthZed Dedicated instances. 
+
+
+## What's Inside
+
+- **OpenTelemetry Collector Configuration**: Examples on how to use the OpenTelemetry Collector to scrape metrics from AuthZed Dedicated and export them to monitoring platforms like Datadog.
+- **Prometheus Configurations**: Preconfigured examples for setting up Prometheus to collect metrics from your AuthZed instances.
+- **Grafana Dashboard**: Sample dashboards for visualizing the collected metrics, providing insights into the performance and health of your AuthZed Dedicated instance.
+
+## Contributing
+
+Contributions are welcome! If you have an example or improvement to share, feel free to submit a pull request.
+
+## Support
+
+If you encounter any issues or have questions, please open an issue in this repository or e-mail support@authzed.com