• Overview
• Installation
  • Ports
• Tools
  • Grafana
    • Configure Datasources
    • Configure Dashboards
    • Configure plugins
  • Grafana Alloy
    • Usage
  • Grafana Loki
  • Grafana Tempo
  • Prometheus
    • Customize Prometheus
    • Addon: Apache Exporter
    • Addon: Nginx Exporter
    • Addon: MySql Exporter
    • Addon: Postgres Exporter
    • Addon: node-exporter
• Credits

This addon contains tools for using OpenTelemetry with a DDEV project.

It contains the following packages:

• Prometheus: an open-source systems monitoring and alerting toolkit.
• Grafana: Query, visualize, alert on, and explore your metrics, logs, and traces.

To install this add-on, run:

ddev add-on get tyler36/ddev-site-metrics
ddev restart

After installation, make sure to commit the .ddev directory to version control.

Grafana is a tool to "Query, visualize, alert on, and explore your metrics, logs, and traces wherever they are stored.".

This addon pre-configures Prometheus as a datasource.

• To include customize, or include additional datasources, update .ddev/grafana/provisioning/datasources/grafana-datasources.yml.

See Grafana data sources.

This add-on pre-configures .ddev/grafana/provisioning/dashboards as the provisioned dashboard folder. See Dashboards. See Dashboard JSON model.

To install a plugin, create or update .ddev/docker-compose.grafana_custom.yaml. Replace <plugin-id> with the plugin ID.

services:
  grafana:
    environment:
      - GF_PLUGINS_PREINSTALL=<plugin-id>

To find the plugin ID:

• visit All plugins for Grafana.

• search for the desired plugin.

• click the "Installation" tab.

• Look at the "Install the Panel" code. In the below example, grafana-clock-panel is the plugin ID.

  grafana-cli plugins install grafana-clock-panel

Grafana Alloy can collect, process, and export telemetry signals to scale and future-proof your observability approach.

This addon configures Grafana Alloy to collect and process:

• Docker logs (alloy/docker.alloy),
• Grafana Alloy logs (alloy/alloy-logs.alloy)
• Enable live debugging of Alloy pipelines, where supported
• Adds a pipeline to a DDEV-supported Grafana Loki process

To configure Grafana Alloy, add/update files in .ddev/alloy. By default, all files in this directory are loaded and processed.

Grafana Alloy runs within the process on its default port of 12345.

• To open the Grafana Alloy dashboard, run the following command:

ddev alloy

• To reload Grafana Alloy configuration, run the following command:

ddev alloy -r

Grafana Loki is a set of open source components that can be composed into a fully featured logging stack.

Grafana Loki listens on its default port of 3100. To view processed logs, visit Drilldown | Logs in the Grafana dashboard.

ddev launch :3000/a/grafana-lokiexplore-app/explore

Key files include:

• docker-compose.grafana-loki.yaml: loads Grafana Loki image
• loki/local-config.yaml: Grafana Loki configuration file

Key files include:

• docker-compose.grafana-loki.yaml: loads Grafana Loki image
• loki/local-config.yaml: Grafana Loki configuration file

Grafana Tempo is an open-source, easy-to-use, and high-scale distributed tracing backend.

In this add-on, Grafana Alloy forwards open telemetry data it receives to Grafana Tempo for processing (./alloy/otelcol.alloy). Grafana Tempo datasource is pre-configured in Grafana allowing a centralized location for interacting with traces.

• To configure Grafana Tempo, update .ddev/tempo/tempo-config.yaml and restart DDEV.
• To forward Grafana Tempo traces to Grafana, update .ddev/.env.grafana-tempo

OTEL_SERVICE_NAME="tempo"
OTEL_EXPORTER_OTLP_ENDPOINT="http://grafana-alloy:4318"

Prometheus is an open-source systems monitoring and alerting toolkit originally built at SoundCloud.

Prometheus collects and stores its metrics as time series data, i.e. metrics information is stored with the timestamp at which it was recorded, alongside optional key-value pairs called labels.

To open Prometheus: ddev prometheus or ddev launch :9090 (assuming the default port).

Prometheus is configured via ./.ddev/prometheus/prometheus.yml. This addon provides an example, but need to customize it for your use-case.

Prometheus's main configuration is in .ddev/prometheus/prometheus.yml. To customize, take ownership by removing #ddev-generated and making the changes as required.

Developers can add scrape_confi details to this file, as shown below.

global:
  scrape_interval: 5s  # How often Prometheus scrapes data

scrape_configs:
  - job_name: 'web'
    metrics_path: '/metrics'
    static_configs:
      - targets: ['web'] # Change to your app's hostname and port. Here, we use DDEV web container.

However, this Prometheus will try to load .ddev/prometheus/scrape-*.yml files. Inversely, removing one of these scrap files will disable it. View .ddev/prometheus/scrape-*.yml for more information.

• To customize the default port, update .ddev/.env

PROMETHEUS_HTTPS_PORT=9090

The Apache Exporter uses lusotycoon/apache-exporter to monitor the apache webs service.

This addon pre-configures the Apache exporter for a DDEV environment.

Key files include:

• docker-compose.apache-exporter.yaml: loads Apache exporter image
• apache/server-status.conf: Add '/server-status' endpoint for Apache status page.

To expose the status page:

# .ddev/config.webserver.yaml
web_extra_exposed_ports:
  - name: webserver
    container_port: 8080
    http_port: 8081
    https_port: 8080

The included dashboard is extended from apache-http-mixin.

The Nginx Exporter uses NGINX Prometheus exporter to monitor NGINX or NGINX Plus using Prometheus.

This addon pre-configures the Nginx Prometheus exporter for a DDEV environment In additional, an example dashboard is available in Grafana.

Key files include:

• docker-compose.nginx-exporter.yaml: loads NGINX Prometheus exporter image
• .ddev/nginx_full/stub_status.conf: Exposes stub statistics from Nginx

MySql Exporter exports MySQL server metrics into Prometheus. The metrics can be used in Grafana:

• monitor the health of the container
• detect slow queries
• detect issue during stress tests

This addon includes an example dashboard inspired by MySQL Overview.

To use, ensure the .ddev/prometheus/prometheus.yml file scrapes the endpoint:

scrape_configs:
  ...
  # Get exposed MySQL metrics
  - job_name: mysql
    metrics_path: /probe
    params:
      # Not required. Will match value to child in config file. Default value is `client`.
      auth_module: [client.servers]
    static_configs:
      - targets:
        # All mysql hostnames or unix sockets to monitor.
        - db:3306
        # Uncomment to target unix sockets.
        # - unix:///run/mysqld/mysqld.sock
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        # The mysqld_exporter host:port
        replacement: mysql-exporter:9104

Postgres-exporter exposes PostgreSQL server metrics to Prometheus.

To use, ensure the .ddev/prometheus/prometheus.yml file scrapes the endpoint:

scrape_configs:
  ...
  # Get exposed Postgres metrics
  - job_name: 'postgres'
    static_configs:
      - targets: ['postgres-exporter:9187']

Key files include:

• docker-compose.postgres-exporter.yaml: loads Postgres-exporter image

Exposed metrics use the following prefixes: pg and postgres.

Node Exporter is a Prometheus exporter for hardware and OS metrics exposed by *NIX kernels, written in Go with pluggable metric collectors.

To use, ensure the .ddev/prometheus/prometheus.yml file scrapes the endpoint:

scrape_configs:
  ...
  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']

By default, node-exporter is accessible via node-exporter:9100 inside the docker container. To change the port,

• update NODE_EXPORTER_HTTP_PORT="9100" in .ddev/.env.
• update the scrape config in .ddev/prometheus/prometheus.yml.
• restart DDEV to apply the changes.

This addon includes an example node dashboard based on Node Exporter Full (v40).

PRs for install steps for specific frameworks are welcome.

Contributed and maintained by @tyler36