Skip to main content
Mapagam

Configuring Console Templates

1. Creating Console Template Files

Console templates in Prometheus are used to customize the display of metrics in the web UI. These templates are written using the Go template language and allow for rich, dynamic views of your metrics.

File Extension Description Usage
.html HTML template files for console views Used to define the layout and structure of metric displays

Example: Basic Console Template Structure

<div class="console">
  <h2>{{.Path}}</h2>
  <div class="metrics">
    {{range .Metrics}}
      <div class="metric">
        <h3>{{.Name}}</h3>
        <pre>{{.Value}}</pre>
      </div>
    {{end}}
  </div>
</div>
Note: Console templates must be placed in the consoles directory within your Prometheus configuration path.
Warning: Template files must be valid Go templates; invalid syntax will cause Prometheus to fail to load the console.

2. Using Template Syntax

Prometheus console templates use the Go template syntax for rendering. The templates are processed using the Go text/template package.

Feature Description Example
Template Variables Variables are accessed using .VariableName {{ .instance }}
Functions Template functions are used for processing data {{ printf "%0.2f" .value }}
Actions Control flow actions like {{ if }}, {{ range }} {{ if .value }}{{ .value }}{{ end }}

Example: Basic Template Syntax

<div>
  <h2>Instance: {{ .instance }}</h2>
  <p>Value: {{ printf "%.2f" .value }}</p>
</div>

Example: Conditional Rendering

<div>
  {{ if .value }}
    <p>Value is: {{ .value }}</p>
  {{ else }}
    <p>No value available</p>
  {{ end }}
</div>

Example: Looping Through Data

<ul>
{{ range .instances }}
  <li>{{ . }}</li>
{{ end }}
</ul>
Link Type Description Usage Example
dashboard.link Creates a link to a dashboard or external resource Used in navigation templates to provide access to related dashboards or documentation dashboard.link: "https://prometheus.io/docs/prometheus/latest"
external.link Defines an external link to a documentation or support page Helps users navigate to external resources for more information external.link: "https://prometheus.io/docs/alerting/latest"
query.link Generates a link to a specific query or metric in the console Allows quick access to metrics or queries from navigation templates query.link: "http://localhost:9090/graph?g0.expr=up" 
navigation:
  - name: "Prometheus Docs"
    link: "https://prometheus.io/docs/"
  - name: "Alerting Guide"
    link: "https://prometheus.io/docs/alerting/latest/"
  - name: "Query Examples"
    link: "http://localhost:9090/graph?g0.expr=up"
Note: Navigation links can be customized per user or role using template variables.

4. Querying Metrics in Templates

Template Function Description Example
query Executes a PromQL query and returns the result as a vector or scalar {{ query "up" }}
query_range Executes a PromQL query over a time range and returns a matrix {{ query_range "rate(http_requests_total[5m])" "1h" }}
vector Creates a vector from a scalar value or string {{ vector 10 }}

Example: Using query function

<div>
  <h3>Up Nodes</h3>
  <ul>
    {{ range query "up" }}
      <li>{{ .metric.instance }} - {{ .value }}</li>
    {{ end }}
  </ul>
</div>

Example: Using query_range function

<div>
  <h3>HTTP Request Rate</h3>
  <pre>{{ query_range "rate(http_requests_total[5m])" "1h" }}</pre>
</div>
Note: The query and query_range functions are part of the PromQL template engine used in Grafana dashboards and Prometheus console templates.

5. Creating Dynamic Dashboards

Example: Basic Dashboard Configuration

# prometheus.yml
rule_files:
  - "alerting.rules.yml"

scrape_configs:
  - job_name: "node"
    static_configs:
      - targets: ['localhost:9100']

# Console templates
console_libraries:
  - /etc/prometheus/console-libs

consoles:
  - /etc/prometheus/consoles
Property Description Default
console_libraries Path to directory containing shared libraries for console templates None
consoles Path to directory containing console template files None
Note: Console templates use the Go template engine. Templates must be valid Go templates.

Example: Dashboard Template with Metrics

<!-- consoles/node.html -->
<h1>Node Exporter Dashboard</h1>

<div class="row">
  <div class="col-md-6">
    <h2>CPU Usage</h2>
    <div class="graph">
      <img src="{{'rate(node_cpu_seconds_total[5m])' | query_url}}">
    </div>
  </div>

  <div class="col-md-6">
    <h2>Memory Usage</h2>
    <div class="graph">
      <img src="{{'node_memory_MemAvailable_bytes' | query_url}}">
    </div>
  </div>
</div>

Example: Using Template Functions

<!-- consoles/dashboard.html -->
<h1>Prometheus Console Dashboard</h1>

<div class="metrics">
  <h2>Active Targets</h2>
  <table>
    <tr><th>Job</th><th>Status</th><th>Last Scrape</th></tr>
    {{range query "up"}}
      <tr>
        <td>{{.Labels.job}}</td>
        <td>{{if eq .Value 1}}UP{{else}}DOWN{{end}}</td>
        <td>{{.Value | humanizeDuration}}</td>
      </tr>
    {{end}}
  </table>
</div>

6. Using Template Libraries

Prometheus console templates can leverage external template libraries to enhance functionality and reusability. These libraries provide pre-built components and helpers that simplify the creation of complex dashboards.

Library Description Usage Notes
Grafana Console Templates Templates designed for Grafana's console interface grafana-console-templates Requires Grafana integration
Prometheus Console Toolkit Collection of tools and templates for console customization prometheus-console-toolkit Supports custom template extensions

Example: Using Grafana Console Templates

templates:
  - grafana-console-templates
Note: Template libraries must be compatible with the Prometheus version in use.
Warning: Ensure that external libraries are securely sourced to prevent vulnerabilities.

7. Implementing Graphs

Example: Basic Graph Configuration

prometheus:
  rule_files:
    - "alerting.rules"
  scrape_configs:
    - job_name: "prometheus"
      static_configs:
        - targets: ["localhost:9090"]
    - job_name: "node"
      static_configs:
        - targets: ["localhost:9100"]
Graph Type Description Usage
Line Graph Displays time-series data as continuous lines Use for monitoring trends over time
Bar Chart Shows discrete values using bars Good for comparing metrics across categories
Heatmap Represents data as colors in a grid Effective for visualizing density or frequency
Note: Graphs in Prometheus are typically rendered using Grafana dashboards.

Example: Querying Metrics for Graphs

rate(http_requests_total[5m])

Example: Using Template Variables in Graphs

template:
  - name: "job"
    value: "prometheus"

8. Formatting Metric Values

Format Description Example
bytes Formats numbers as bytes with units (B, KiB, MiB, GiB) 1024 | bytes → 1 KiB
duration Formats durations in seconds to human-readable format 3661 | duration → 1h 1m 1s
percent Formats numbers as percentages (multiplies by 100) 0.75 | percent → 75%
rate Formats rate per second (e.g., bytes/sec) 1024 | rate → 1 KiB/s
time Formats Unix timestamps to readable date/time 1609459200 | time → 2021-01-01 00:00:00

Example: Using bytes formatting in a console template

{{.Value | bytes}}

Example: Using duration formatting in a console template

{{.Value | duration}}

9. Creating Reusable Components

Example: Define a reusable template component for metrics

<div class="metric-card">
  <h4>{{ .Title }}</h4>
  <p>Current Value: {{ .Value }}</p>
</div>
Component Description Usage
metric-card Reusable card component for displaying metrics Include in any dashboard template
alert-badge Badge component for alert status indicators Attach to metric cards or alerts
Note: Template components should be defined in a shared directory to ensure consistency across dashboards.
Warning: Avoid deeply nested components as they can impact rendering performance.

10. Configuring Console Library Path

Property Values Description
console.libraries.path string Path to the directory containing console libraries.
console.libraries.enabled boolean Enables or disables console library loading.

Example: Setting Console Library Path

console:
  libraries:
    path: /opt/prometheus/console_libraries
    enabled: true
Note: The console library path must be accessible to the Prometheus server process.

11. Implementing Conditional Rendering

Feature Description Usage
template Template file path console_template.html
condition Conditional logic expression {{ if eq .Status "up" }}

Example: Basic Conditional in Template

<div>
  {{ if eq .Status "up" }}
    <p>System is operational</p>
  {{ else }}
    <p>System is down</p>
  {{ end }}
</div>
Note: Use {{ if }} blocks to conditionally render content based on metric values or labels.

12. Using Table Formatting

Template Variable Description Example Output
.Name Instance name node_exporter
.Value Instance value 127.0.0.1:9100
.Labels Instance labels {job="node", instance="localhost:9100"}

Example: Table Formatting in Console Templates

<table>
  <tr>
    <th>Name</th>
    <th>Value</th>
    <th>Labels</th>
  </tr>
  {{ range query "up" }}
  <tr>
    <td>{{ .Name }}</td>
    <td>{{ .Value }}</td>
    <td>{{ .Labels }}</td>
  </tr>
  {{ end }}
</table>

Was this article helpful?

Related Cheat Sheets