puppet_operational_dashboards

Table of Contents

• puppet_operational_dashboards
  • Table of Contents
  • Description
  • Setup
    • Prerequisites
    • Note on air-gapped environments
    • Beginning with puppet_operational_dashboards
      • Installing on Puppet Enterprise
      • Installing on Puppet Open Source
      • What puppet_operational_dashboards affects
  • Usage
    • Evaluation order
    • Determining where Telegraf runs
    • Importing archive metrics
  • Default Dashboards Available
    • Puppetserver Performance
    • File Sync Metrics
    • PuppetDB Performance
    • Postgres Performance
    • Limitations
  • Ubuntu Telegraf Package
  • Upgrading from puppet_metrics_dashboard
  • Applying classes on PE 2021.5 and 2021.6
  • Installing on openSUSE 15
    • Troubleshooting
  • Grafana datasource and time interval
  • Telegraf errors
• Supporting Content
  • Articles
  • Videos

Description

This module is a replacement for the puppet_metrics_dashboard module. It is used to configure Telegraf, InfluxDB, and Grafana to collect, store, and display metrics collected from Puppet services. By default, those components are installed on a separate Dashboard node by applying the base class of this module to that node. That class will automatically query PuppetDB for Puppet Infrastructure nodes (Primary server, Compilers, PuppetDB hosts, PostgreSQL hosts) or you can specify them via associated class parameters. It is not recommended to apply the base class of this module to one of your Puppet Infrastructure nodes.

Setup

Prerequisites

Note on air-gapped environments

If you are applying either the puppet_operational_dashboards or puppet_operational_dashboards::telegraf::agent classes to a node that cannot access the internet, it is possible to install packages from either an internal repository or archive sources located within the air gap.

Internal repositories

To use internal repositories, set the following parameters.

For InfluxDB, the following parameters are configurable:

• repo_url to point to a local URL
• repo_gpg_key_url to point to a local URL with the repository's GPG key
• repo_gpg_key_id to specify a different GPG key ID

Alternatively, you may set manage_repo to false to manage the repository configuration yourself.

For Grafana, the equivalent parameters are:

• repo_url
• repo_gpg_key_url
• repo_key_id
• manage_package_repo

For Telegraf, the following parameters are available:

• repo_location
• manage_repo

GPG options are currently not configurable.

Via Hiera it will look like this:

influxdb::manage_repo: true
influxdb::archive_source: false
puppet_operational_dashboards::profile::dashboards::manage_grafana_repo: true
puppet_operational_dashboards::telegraf::agent::manage_archive: false
puppet_operational_dashboards::telegraf::agent::manage_repo: true

That will install all components via their upstream repositories. When you want to use packages but manage repositories on your own, for example because you use Katello or RedHat Satellite:

influxdb::manage_repo: false
influxdb::archive_source: false
puppet_operational_dashboards::profile::dashboards::manage_grafana_repo: false
puppet_operational_dashboards::telegraf::agent::manage_archive: false
puppet_operational_dashboards::telegraf::agent::manage_repo: false

If you intend to use toml template format (default) then influxdb needs to install the toml gem. If you're behind an http proxy you can configure that as well:

influxdb::profile::toml::install_options_server:
  - '-p'
  - 'http://10.88.96.254.3128'
influxdb::profile::toml::install_options_agent:
  - '-p'
  - 'http://10.88.96.254.3128'

Archive sources

To use archive sources, set the following parameters. Note that support for Grafana archives has been deprecated and will need to be installed from a repository or package source.

For InfluxDB, set:

• influxdb::manage_repo to false
• influxdb::archive_source to an internal URL containing the archive file for InfluxDB

For Grafana, set:

• puppet_operational_dashboards::profile::dashboards::grafana_install to package.

Then, set grafana::package_source to an internal URL containing a package for Grafana for your distribution.

For Telegraf, set:

• puppet_operational_dashboards::telegraf::agent::manage_repo to false
• puppet_operational_dashboards::telegraf::agent::manage_archive to true
• puppet_operational_dashboards::telegraf::agent::archive_location to an internal URL containing the archive file for Telegraf

Beginning with puppet_operational_dashboards

Installing on Puppet Enterprise

To Install on Puppet Enterprise:

1. Classify puppet_operational_dashboards::enterprise_infrastructure to a node group that encompasses all Puppet Infrastructure agents. The default node group PE Infrastructure Agent is appropriate.

include puppet_operational_dashboards::enterprise_infrastructure

This will install the toml-rb gem on compiling nodes, and grant the appropriate access to the databases, for the dashboard node on all database nodes.

2. Classify puppet_operational_dashboards to the Puppet agent node to be designated as the Operational Dashboard node.

include puppet_operational_dashboards

This will install and configure Telegraf, InfluxDB, and Grafana.

Please note database access will not be granted until the Puppet agent run on the postgres nodes AFTER the application of puppet_operational_dashboards on the designated dashboard node.

toml-rb gem dependency

The default behavior of this module relies on toml-rb gem to parse epp templates in this module for telegraf inputs.

For Puppet Infrastructure agents, you can specify yaml format which does not require the toml-rb gem:

  class { 'puppet_operational_dashboards::enterprise_infrastructure':
    template_format => 'yaml',
  }

Via Hiera it will look like this:

puppet_operational_dashboards::enterprise_infrastructure::template_format: 'yaml'

This will:

1. Skip toml-rb gem install.
2. Use yaml format templates in this module with stdlib's parseyaml() to prepare input configs for telegraf.

Installing on Puppet Open Source

If using toml template format (default), the toml-rb gem needs to be installed in the Puppetserver gem space, which can be done with the influxdb::profile::toml class in the InfluxDB module.

To collect PostgreSQL metrics, FOSS users can apply the puppet_operational_dashboards::profile::foss_postgres_access class to any postgres nodes to configure authentication and grants for a telegraf user to connect. This class has a dependency on the puppetlabs/puppetdb and puppetlabs/postgresql modules, and you must use the puppetlabs/puppetdb module to configure SSL for postgres. See the documentation here.

You may also configure the connection options used by the Telegraf client when querying postgres. These options can be set using the puppet_operational_dashboards::telegraf::agent::postgres_options class parameter.

The easiest way to get started using this module is by including the puppet_operational_dashboards class to install and configure Telegraf, InfluxDB, and Grafana. Note that if you are using toml template format (default) you also need to install the toml-rb gem according to the documentation.

include puppet_operational_dashboards

What puppet_operational_dashboards affects

Installing the module will:

• Install and configure InfluxDB using the puppetlabs/influxdb module
• Install and configure Telegraf to collect metrics from your PE infrastructure. FOSS users can specify a list of infrastructure nodes via the puppet_operational_dashboards::telegraf::agent parameters.
• Install and configure Grafana with several dashboards to display data from InfluxDB

Note that this will save an InfluxDB administrative token to the user's home directory, typically /root/.influxdb_token. The puppetlabs/influxdb types and providers can make use of this file during catalog application. The manifests in this module are also able to use it via deferred functions, which also run on the agent as the first step of catalog application. Therefore, it is possible to use this file for all token-based operations in this module, and no further configuration is required.

It is also possible to specify this token via the influxdb::token parameter in hiera. The Telegraf token used by the telegraf service and Grafana datasource can also be set via puppet_operational_dashboards::telegraf_token. These are both Sensitive strings, so the recommended way to use them is to encrypt them with hiera-eyaml and use the encrypted value in hiera data. After setting up a hierarchy to use the eyaml backend, the values can be added to hiera data and automatically converted to Sensitive:

influxdb::token: <eyaml_encrypted_string>
lookup_options:
   influxdb::token:
     convert_to: "Sensitive"

These parameters take precedence over the file on disk if both are specified.

Usage

Accessing Grafana

To access Grafana, use the following in your browser of choice: http://[AGENT IP ADDRESS]:3000

When first accessing Grafana, the default login and password are as follows:

Username: admin Password: admin

Upon first sign in, you will then be prompted to change your password, skip this step and proceed to the dashboard.

Evaluation order

When using the default configuration options and the deferred function to retreive the Telegraf token, note that it will not be available during the initial Puppet agent run that creates all of the resources. A second run is required to retrieve the token and update the resources that use it. If you are seeing authentication errors from Telegraf and Grafana, make sure the Puppet agent has been run twice and that the token has made its way to the Telegraf service config file:

/etc/systemd/system/telegraf.service.d/override.conf

Determining where Telegraf runs

Which hosts a node collects metrics from is determined by the puppet_operational_dashboards::telegraf::agent::collection_method parameter. By default, the puppet_operational_dashboards class will collect metrics from all nodes in a PE infrastructure. If you want to change this behavior, set collection_method to local or none. Telegraf can be run on other nodes by applying the puppet_operational_dashboards::telegraf::agent class to them, for example:

class {'puppet_operational_dashboards::telegraf::agent':
  collection_method => 'local',
  token => <my_sensitive_token>,
}

Importing archive metrics

Metrics archives output by the Puppet metrics collector can be imported into InfluxDB using Telegraf and the scripts in the examples/ directory. See ARCHIVES.md for more.

Default Dashboards Available

Puppetserver Performance

This dashboard is to inspect Puppet server performance and troubleshoot the pe-puppetserver service. Available panels:

• Puppetserver Performance This is a composite panel consisting of the following JRuby related metrics:
  • Average free JRubies
  • Average requested JRubies
  • Average JRuby borrow time
  • Average JRuby wait time
• Heap Memory and Uptime This panel displays the following JVM metrics:
  • Heap Committed
  • Heap Used
  • Uptime
• Average Requested JRubies
• Average Borrow/Compile Time
• Average Free JRubies
• Average Wait Time
• HTTP Client Metrics This panel displays the various network related metrics performed by Puppet server. Examples include:
  • puppetdb.query.full_response
  • facts.find.full_response
• Borrow Timers Mean Average duration api requests require borrowing a JRuby from the pool
• Borrow Timers Rate Rate at which Puppet server performs the above api requests
• Function Timers Average duration of functions run as part of catalog compilations
• Function Timers Count Rate at which Puppet server performs the above api requests

Use Case

• Puppetserver service performance degraded
• 503 responses to agent requests
• Agent unable to get catalog
• Inspect performance for a particular type of request
• Inspect which type of request could be a performance bottleneck

File Sync Metrics

This dashboard is to inspect File-sync related performance. Available Graphs:

• Number of Fetch / Commits vs Lock wait / held
  • Average Lock Held Time
  • Average Lock Wait Time
  • Number of Commits
  • Number of Fetches
• File-Sync timing - Client Services
  • Average Clone Time
  • Average Fetch Time
  • Average Sync Time
  • Average Sync Clean Time
• File-Sync timing - Storage Services
  • Average Commit add / rm Time
  • Average Commit time
  • Average Clean Check time
  • Average Pre-commit Hook Time

Use Case

• Code Manager takes a significant time or fails to deploy code
• Puppetserver frequently locked due to file sync
• Compilers do not have the latest code available

PuppetDB Performance

This dashboard is to inspect PuppetDB performance and troubleshoot the pe-puppetdb service. Available panels:

• Heap
• Commands Per Second
• Command Processing Time
• Queue Depth
• Replace Catalog Time
• Replace Facts Time
• Store Report Time
• Average Read Duration
• Read Pool Pending Connections
• Average Write Duration
• Write Pool Pending Connections

Use Case

• Any PuppetDB performance issues
• Troubleshooting Read/Write Pool Errors

Postgres Performance

This dashboard is to inspect PostgreSQL database performance. Available panels:

• Temp Files Changes in temp file sizes per database over the given time interval
• Sizes by Database (total) Total size of each database, including tables, indexes, and toast
• Sizes by Table Size of each table, not including indexes or toast
• Sizes by Index
• Sizes by Toast
• Autovacuum Activity
• Vacuum Activity - (not auto, not full)
• I/O - heap toast and index - hits / reads
• Disk Block Reads (Heap) Changes in the number of disks blocks reads by postgres heap files per table. This indicates the value needed to be retrieved from disk instead of the cache.
• Cache Reads (Heap) Changes in the number of cache reads by postgres heap files per table. This indicates the value was retrieved from the cache.
• Disk Block Reads (Index) Same as above panel, but for indexes
• Cache Reads (Index) Same as above panel, but for indexes
• Disk Block Reads (Toast) Same as above panel, but for toast data
• Cache Reads (Toast) Same as above panel, but for toast data
• Live / Dead Tuples
• Deadlocks

Use Cases

• Monitor table sizes
• Monitor Deadlocks and Slow Queries
• Any PostgreSQL performance issues

Limitations

Ubuntu Telegraf Package

Currently, only the latest Telegraf package is provided by the Ubuntu repository. Therefore, the only allowed value for puppet_operational_dashboards::telegraf::agent::version is latest. Setting this parameter to a different value on Ubuntu will produce a warning.

Upgrading from puppet_metrics_dashboard

This module uses InfluxDB 2.x, while puppet_metrics_dashboard uses 1.x. This module does not currently provide an option to upgrade between these versions, so it is recommended to either install this module on a new node or manually upgrade. See the InfluxDB docs for more information about upgrading.

Applying classes on PE 2021.5 and 2021.6

On Puppet Enterprise versions 2021.5 and 2021.6, there is an issue when applying either the puppet_operational_dashboards::enterprise_infrastructure or puppet_operational_dashboards::profile::postgres_access classes in a user manifest. Doing so may result in an error such as:

Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Evaluation Error: Comparison of: Undef Value < Integer, is not possible. Caused by 'Only Strings, Numbers, Timespans, Timestamps, and Versions are comparable'

This is due to an ordering issue with the cert_allowlist_entry defined type. The workaround is to apply the classes via the Console, for example by applying puppet_operational_dashboards::enterprise_infrastructure to the PE Infrastructure Agent node group. See Installing on Puppet Enterprise.

This issue only affect PE versions 2021.5 and 2021.6. Earlier versions are not affected, and later releases will include a fix to the defined type.

Installing on openSUSE 15

On some versions of openSUSE 15, the insserv-compat package may be required to enable the Grafana service. If you see an error such as:

Error: /Stage[main]/Grafana::Service/Service[grafana]/ensure: change from 'stopped' to 'running' failed: Could not enable grafana-server:

This is due to the missing package:

Synchronizing state of grafana-server.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
Executing: /usr/lib/systemd/systemd-sysv-install enable grafana-server
/sbin/insserv: No such file or directory

Installing the insserv-compat resolves the error.

Troubleshooting

If data is not displaying in Grafana or you see errors in Telegraf collections, try checking the following items.

Grafana datasource and time interval

A common reason for not seeing data in the dashboards is choosing the wrong datasource or time interval. Double check that you have selected a datasource and window of time for which metrics have been collected. Also, check that the server filter at the top of the dashboard contains valid entries.

Also, note that Telegraf performs its first collection after the first collection interval has passed. You may need to wait for this to pass, or manually test using the method below.

Datasources can be tested via the "Data Sources" configuration page in Grafana. Select the datasource, e.g. influxdb_puppet, and click the "Test" button. Note that because this is a "provisioned datasource," it cannot be edited in the UI.

Telegraf errors

A good way to test Telegraf collection is to use the --test option. After logging into the node running telegraf, first export your token:

export INFLUX_TOKEN=<token>

The token can either be the admin token written to /root/.influxdb_token by default, or the puppet telegraf token used specifically for Telegraf. See REFERENCE.md for more information.

Prepending a space before the export command will prevent the token from being written to you shell's history.

Then, test the collection:

telegraf --test --debug --config /etc/telegraf/telegraf.conf --config-directory /etc/telegraf/telegraf.d/

Services can also be tested individually, for example:

telegraf --test --debug --config /etc/telegraf/telegraf.conf --config /etc/telegraf/telegraf.d/puppetserver_metrics.conf

will only collect Puppet server metrics.

---

Supporting Content

Articles

The Support Knowledge base is a searchable repository for technical information and how-to guides for all Puppet products.

This Module has the following specific Article(s) available:

1. Manage the installation and configuration of metrics dashboards using the puppetlabs-puppet_operational_dashboards module for Puppet Enterprise
2. Monitor the performance of your PuppetDB
3. High swap usage on your primary server or replica in Puppet Enterprise

Videos

The Support Video Playlist is a resource of content generated by the support team

This Module has the following specific video content available:

1. Puppet Metrics Overview

2. Collecting and Displaying Puppet Metrics

3. Interpreting Puppet Metrics

   ---

Reference

Table of Contents

Classes

• puppet_operational_dashboards: Installs Telegraf, InfluxDB, and Grafana to collect and display Puppet metrics
• puppet_operational_dashboards::enterprise_infrastructure: Installs dependancies for Operational dashboards on PE infrastructure components
• puppet_operational_dashboards::profile::dashboards: Installs Grafana and several dashboards to display Puppet metrics. Included via the base class.
• puppet_operational_dashboards::profile::foss_postgres_access: Allows Telegraf to connect and collect metrics from postgres nodes
• puppet_operational_dashboards::profile::postgres_access: Allows Telegraf to connect and collect metrics from postgres nodes
• puppet_operational_dashboards::telegraf::agent: Installs and configures Telegraf to query hosts in a Puppet infrastructure. Included by the base class

Defined types

• puppet_operational_dashboards::telegraf::config: Defined type to create Telegraf configurations for a given service

Functions

• puppet_operational_dashboards::hosts_with_profile: function used to determine hosts with a profile class
• puppet_operational_dashboards::pe_profiles_on_host: function used to determine hosts with a Puppet Enterprise profile

Plans

• puppet_operational_dashboards::load_metrics: A plan created with bolt plan new.
• puppet_operational_dashboards::provision_dashboard: A plan to provision a non-SSL operational dashboards node

Classes

puppet_operational_dashboards

Installs Telegraf, InfluxDB, and Grafana to collect and display Puppet metrics

Examples

Basic usage

include puppet_operational_dashboards

class {'puppet_operational_dashboards':
  manage_influxdb => false,
  influxdb_host   => '<influxdb_fqdn>',
}

Parameters

The following parameters are available in the puppet_operational_dashboards class:

• manage_influxdb
• influxdb_host
• influxdb_port
• initial_org
• initial_bucket
• influxdb_bucket_retention_rules
• influxdb_token
• telegraf_token_name
• manage_telegraf
• manage_telegraf_token
• use_ssl
• use_system_store
• influxdb_token_file
• telegraf_token
• include_pe_metrics
• manage_system_board
• template_format

manage_influxdb

Data type: Boolean

Whether to manage installation and configuration of InfluxDB.

Default value: true

influxdb_host

Data type: String

FQDN of the InfluxDB host.

Default value: lookup(influxdb::host, undef, undef, $facts['networking']['fqdn'])

influxdb_port

Data type: Integer

Port used by the InfluxDB service.

Default value: lookup(influxdb::port, undef, undef, 8086)

initial_org

Data type: String

Name of the InfluxDB organization to configure.

Default value: lookup(influxdb::initial_org, undef, undef, 'puppetlabs')

initial_bucket

Data type: String

Name of the InfluxDB bucket to configure and query.

Default value: lookup(influxdb::initial_bucket, undef, undef, 'puppet_data')

influxdb_bucket_retention_rules

Data type: Array

Value for the initial InfluxDB bucket retention rules, Values are the same as in the influx_bucket type of the InfluxDB module.

Default value: [{ 'type' => 'expire', 'everySeconds' => 7776000, 'shardGroupDurationSeconds' => 604800 }]

influxdb_token

Data type: Optional[Sensitive[String]]

InfluxDB admin token in Sensitive format. See the puppetlabs/influxdb documentation for more information about this token.

Default value: lookup(influxdb::token, undef, undef, undef)

telegraf_token_name

Data type: String

Name of the token to retrieve from InfluxDB if not given $telegraf_token.

Default value: 'puppet telegraf token'

manage_telegraf

Data type: Boolean

Whether to manage installation and configuration of Telegraf.

Default value: true

manage_telegraf_token

Data type: Boolean

Whether to create and manage a Telegraf token with permissions to query buckets in the default organization.

Default value: true

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB.

Default value: true

use_system_store

Data type: Boolean

Whether to use the system CA bundle.

Default value: lookup(influxdb::use_system_store, undef, undef, false)

influxdb_token_file

Data type: String

Location on disk of an InfluxDB admin token. This file is written to by the influxdb class during installation and read by the type and providers, as well Deferred functions in this module.

Default value:

lookup(influxdb::token_file, undef, undef, $facts['identity']['user'] ? {
      'root'  => '/root/.influxdb_token',
      default => "/home/${facts['identity']['user']}/.influxdb_token"
  })

telegraf_token

Data type: Optional[Sensitive[String]]

Telegraf token in Sensitive format.

Default value: undef

include_pe_metrics

Data type: Boolean

Whether to include Filesync and Orchestrator dashboards

Default value:

$settings::module_groups ? {
    /pe_only/ => true,
    default   => false

manage_system_board

Data type: Boolean

Whether the System Performance dashboard should be added to grafana

Default value: true

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: 'toml'

puppet_operational_dashboards::enterprise_infrastructure

When applied to an appropriate node group this class applies the toml gem and database access On appropriate infrastructure nodes in PE

Examples

include puppet_operational_dashboards::enterprise_infrastructure

Parameters

The following parameters are available in the puppet_operational_dashboards::enterprise_infrastructure class:

• profiles
• template_format

profiles

Data type: Array[String]

Array of PE profiles on the node with this class applied.

Default value: puppet_operational_dashboards::pe_profiles_on_host()

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: 'toml'

puppet_operational_dashboards::profile::dashboards

Installs Grafana and several dashboards to display Puppet metrics. Included via the base class.

Examples

Basic usage

include puppet_operational_dashboards

class {'puppet_operational_dashboards::profile::dashboards':
  token         => '<my_sensitive_token>',
  influxdb_host => '<influxdb_fqdn>',
  influxdb_port => 8086,
  initial_bucket => '<my_bucket>',
}

Parameters

The following parameters are available in the puppet_operational_dashboards::profile::dashboards class:

• token
• grafana_host
• grafana_port
• grafana_use_ssl
• manage_grafana_ssl
• grafana_cert_file
• grafana_key_file
• grafana_cert_file_source
• grafana_key_file_source
• grafana_timeout
• grafana_password
• grafana_version
• grafana_datasource
• grafana_install
• use_ssl
• use_system_store
• manage_grafana
• manage_grafana_repo
• influxdb_host
• influxdb_port
• influxdb_bucket
• telegraf_token_name
• influxdb_token_file
• provisioning_datasource_file
• include_pe_metrics
• manage_system_board
• system_dashboard_version

token

Data type: Optional[Sensitive[String]]

Token in Sensitive format used to query InfluxDB. The token must grant priviledges to query the associated bucket in InfluxDB

Default value: $puppet_operational_dashboards::telegraf_token

grafana_host

Data type: String

FQDN of the Grafana host.

Default value: $facts['networking']['fqdn']

grafana_port

Data type: Integer

Port used by the Grafana service.

Default value: 3000

grafana_use_ssl

Data type: Boolean

Enable use of HTTPS/SSL for Grafana.

Default value: false

manage_grafana_ssl

Data type: Boolean

Whether to manage the SSL certificate files when using the grafana_use_ssl parameter.

Default value: true

grafana_cert_file

Data type: Stdlib::Absolutepath

SSL certificate file to use when 'grafana_use_ssl' and 'manage_grafana' are enabled.

Default value: '/etc/grafana/client.pem'

grafana_key_file

Data type: Stdlib::Absolutepath

SSL private key file to use when 'grafana_use_ssl' and 'manage_grafana' are enabled.

Default value: '/etc/grafana/client.key'

grafana_cert_file_source

Data type: Stdlib::Absolutepath

SSL certificate file to use as the source for the grafana_cert_file parameter.

Default value: "/etc/puppetlabs/puppet/ssl/certs/${trusted['certname']}.pem"

grafana_key_file_source

Data type: Stdlib::Absolutepath

SSL certificate file to use as the source for the grafana_key_file parameter.

Default value: "/etc/puppetlabs/puppet/ssl/private_keys/${trusted['certname']}.pem"

grafana_timeout

Data type: Integer

How long to wait for the Grafana service to start.

Default value: 10

grafana_password

Data type: Sensitive[String]

Grafana admin password in Sensitive format.

Default value: Sensitive('admin')

grafana_version

Data type: String

Version of the Grafana package to install.

Default value: '8.5.27'

grafana_datasource

Data type: String

Name to use for the Grafana datasource.

Default value: 'influxdb_puppet'

grafana_install

Data type: String

Method to use for installing Grafana.

Default value:

$facts['os']['family'] ? {
    /(RedHat|Debian)/ => 'repo',
    default           => 'package'

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB.

Default value: $puppet_operational_dashboards::use_ssl

use_system_store

Data type: Boolean

Whether to use the system CA bundle.

Default value: $puppet_operational_dashboards::use_system_store

manage_grafana

Data type: Boolean

Whether to manage installation and configuration of Grafana.

Default value: true

manage_grafana_repo

Data type: Boolean

Whether to manage the Grafana repository definition.

Default value: true

influxdb_host

Data type: String

FQDN of the InfluxDB host.

Default value: $puppet_operational_dashboards::influxdb_host

influxdb_port

Data type: Integer

Port used by the InfluxDB service.

Default value: $puppet_operational_dashboards::influxdb_port

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to query.

Default value: $puppet_operational_dashboards::initial_bucket

telegraf_token_name

Data type: String

Name of the token to retrieve from InfluxDB if not given $token

Default value: $puppet_operational_dashboards::telegraf_token_name

influxdb_token_file

Data type: Stdlib::Absolutepath

Location on disk of an InfluxDB admin token. This token is used in this class in a Deferred function call to retrieve a Telegraf token if $token is unset

Default value: $puppet_operational_dashboards::influxdb_token_file

provisioning_datasource_file

Data type: Stdlib::Absolutepath

Location on disk to store datasource definition

Default value: '/etc/grafana/provisioning/datasources/influxdb.yaml'

include_pe_metrics

Data type: Boolean

Whether to include Filesync and Orchestrator dashboards

Default value: $puppet_operational_dashboards::include_pe_metrics

manage_system_board

Data type: Boolean

Whether the System Performance dashboard should be created

Default value: $puppet_operational_dashboards::manage_system_board

system_dashboard_version

Data type: Enum['v1', 'v2', 'all']

Version of the system dashboard to manage. v2 is compatible with puppet_metrics_collector version 7 and up

Default value: 'v2'

puppet_operational_dashboards::profile::foss_postgres_access

Allows Telegraf to connect and collect metrics from postgres nodes

Examples

Basic usage

include puppet_operational_dashboards::profile::foss_postgres_access

Parameters

The following parameters are available in the puppet_operational_dashboards::profile::foss_postgres_access class:

• telegraf_hosts
• telegraf_user

telegraf_hosts

Data type: Array

A list of FQDNs running Telegraf to allow access to

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_operational_dashboards::Telegraf::Agent')

telegraf_user

Data type: String

Username for the Telegraf client to use in the postgres connection string

Default value: 'telegraf'

puppet_operational_dashboards::profile::postgres_access

Allows Telegraf to connect and collect metrics from postgres nodes

Examples

Basic usage

include puppet_operational_dashboards::profile::postgres_access

Parameters

The following parameters are available in the puppet_operational_dashboards::profile::postgres_access class:

• telegraf_hosts

telegraf_hosts

Data type: Array

A list of FQDNs running Telegraf to allow access to

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_operational_dashboards::Telegraf::Agent')

puppet_operational_dashboards::telegraf::agent

Installs and configures Telegraf to query hosts in a Puppet infrastructure. Included by the base class

Examples

Basic usage

include puppet_operational_dashboards

class {'puppet_operational_dashboards::telegraf::agent':
  token => '<sensitive_telegraf_token>',
}

Parameters

The following parameters are available in the puppet_operational_dashboards::telegraf::agent class:

• token
• influxdb_host
• influxdb_port
• influxdb_org
• influxdb_bucket
• use_ssl
• use_system_store
• manage_ssl
• manage_repo
• manage_archive
• manage_user
• ssl_cert_file
• ssl_key_file
• ssl_ca_file
• puppet_ssl_cert_file
• puppet_ssl_key_file
• puppet_ssl_ca_file
• insecure_skip_verify
• version
• archive_location
• archive_install_dir
• collection_method
• collection_interval
• puppetserver_hosts
• puppetdb_hosts
• postgres_hosts
• orchestrator_hosts
• profiles
• local_services
• token_name
• influxdb_token_file
• http_timeout_seconds
• include_pe_metrics
• telegraf_user
• telegraf_postgres_password
• postgres_port
• postgres_options
• template_format

token

Data type: Optional[Sensitive[String]]

Telegraf token in Sensitive format.

Default value: $puppet_operational_dashboards::telegraf_token

influxdb_host

Data type: String

FQDN of the InfluxDB host.

Default value: $puppet_operational_dashboards::influxdb_host

influxdb_port

Data type: Integer

Port used by the InfluxDB service.

Default value: $puppet_operational_dashboards::influxdb_port

influxdb_org

Data type: String

Name of the InfluxDB organization.

Default value: $puppet_operational_dashboards::initial_org

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to query.

Default value: $puppet_operational_dashboards::initial_bucket

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB.

Default value: $puppet_operational_dashboards::use_ssl

use_system_store

Data type: Boolean

Whether to use the system CA bundle.

Default value: $puppet_operational_dashboards::use_system_store

manage_ssl

Data type: Boolean

Whether to manage Telegraf ssl configuration.

Default value: true

manage_repo

Data type: Boolean

Whether to install Telegraf from a repository.

manage_archive

Data type: Boolean

Whether to install Telegraf from an archive source.

Default value: !$manage_repo

manage_user

Data type: Boolean

Whether to manage the telegraf user when installing from archive.

Default value: true

ssl_cert_file

Data type: Stdlib::Absolutepath

SSL certificate to be used by the telegraf service.

Default value: "/etc/puppetlabs/puppet/ssl/certs/${trusted['certname']}.pem"

ssl_key_file

Data type: Stdlib::Absolutepath

Private key used in the CSR for the certificate specified by $ssl_cert_file.

Default value: "/etc/puppetlabs/puppet/ssl/private_keys/${trusted['certname']}.pem"

ssl_ca_file

Data type: Stdlib::Absolutepath

CA certificate issued by the CA which signed the certificate specified by $ssl_cert_file.

Default value: '/etc/puppetlabs/puppet/ssl/certs/ca.pem'

puppet_ssl_cert_file

Data type: Stdlib::Absolutepath

SSL certificate to be used by the telegraf inputs.

Default value: "/etc/puppetlabs/puppet/ssl/certs/${trusted['certname']}.pem"

puppet_ssl_key_file

Data type: Stdlib::Absolutepath

Private key used in the CSR for the certificate specified by $puppet_ssl_cert_file.

Default value: "/etc/puppetlabs/puppet/ssl/private_keys/${trusted['certname']}.pem"

puppet_ssl_ca_file

Data type: Stdlib::Absolutepath

CA certificate issued by the CA which signed the certificate specified by $puppet_ssl_cert_file.

Default value: '/etc/puppetlabs/puppet/ssl/certs/ca.pem'

insecure_skip_verify

Data type: Boolean

Skip verification of SSL certificate.

Default value: true

version

Data type: String

Version of the Telegraf package to install.

archive_location

Data type: String

URL containing an archive source for the telegraf package. Defaults to downloading $version from dl.influxdata.com

Default value: "https://dl.influxdata.com/telegraf/releases/telegraf-${version.split('-')[0]}_linux_amd64.tar.gz"

archive_install_dir

Data type: String

Directory to install $archive_location to.

Default value: '/opt/telegraf'

collection_method

Data type: Enum['all', 'local', 'none']

Determines how metrics will be collected. 'all' will query all Puppet services across all Puppet infrastructure hosts from the node with this class applied. 'local' will query all Puppet services on the node with this class applied. 'none' will not query any services from the node with this class applied.

Default value: 'all'

collection_interval

Data type: String

How frequently to collect metrics.

Default value: '10m'

puppetserver_hosts

Data type: Array

Array of Puppet server hosts to collect metrics from. FOSS users need to supply a list of FQDNs.

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Master')

puppetdb_hosts

Data type: Array

Array of PuppetDB hosts to collect metrics from. FOSS users need to supply a list of FQDNs.

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Puppetdb')

postgres_hosts

Data type: Array

Array of Postgres hosts to collect metrics from. FOSS users need to supply a list of FQDNs.

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Database')

orchestrator_hosts

Data type: Array

Array of Orchestrator hosts to collect metrics from. FOSS users need to supply a list of FQDNs.

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Orchestrator')

profiles

Data type: Array[String]

Array of PE profiles on the node with this class applied. Used when collection_method is set to 'local'. FOSS users can use the $local_services parameter.

Default value: puppet_operational_dashboards::pe_profiles_on_host()

local_services

Data type: Array[String]

Array of FOSS services to collect from when collection_method is set to 'local'.

Default value: []

token_name

Data type: String

Name of the token to retrieve from InfluxDB if not given $token

Default value: $puppet_operational_dashboards::telegraf_token_name

influxdb_token_file

Data type: String

Location on disk of an InfluxDB admin token. This token is used in this class in a Deferred function call to retrieve a Telegraf token if $token is unset

Default value: $puppet_operational_dashboards::influxdb_token_file

http_timeout_seconds

Data type: Integer[1]

Timeout for HTTP Telegraf inputs. Might be usefull in huge environments with slower API responses

Default value: 5

include_pe_metrics

Data type: Boolean

Whether to include Filesync and Orchestrator dashboards

Default value: $puppet_operational_dashboards::include_pe_metrics

telegraf_user

Data type: String

Username for the Telegraf client to use in the postgres connection string

Default value: 'telegraf'

telegraf_postgres_password

Data type: Optional[Sensitive[String]]

Optional Sensitive password for the Telegraf client to use in the postgres connection string

Default value: undef

postgres_port

Data type: Integer

Port for the Telegraf client to use in the postgres connection string

Default value: 5432

postgres_options

Data type: Hash

Hash of options for the Telegraf client to use as connection parameters in the postgres connection string

Default value:

{
    'sslmode'     => 'verify-full',
    'sslkey'      => '/etc/telegraf/puppet_key.pem',
    'sslcert'     => '/etc/telegraf/puppet_cert.pem',
    'sslrootcert' => '/etc/telegraf/puppet_ca.pem',
  }

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: $puppet_operational_dashboards::template_format

Defined types

puppet_operational_dashboards::telegraf::config

Defined type to create Telegraf configurations for a given service

Parameters

The following parameters are available in the puppet_operational_dashboards::telegraf::config defined type:

• service
• protocol
• hosts
• ensure
• http_timeout_seconds
• template_format

service

Data type: String

Name of the service to query. Is the title of the resource.

Default value: $title

protocol

Data type: Enum['https', 'http']

Protocol to use in requests, either https or http

hosts

Data type: Array[String[1]]

Array of hosts running the service

ensure

Data type: Enum['present', 'absent']

Whether the resource should be present or absent

Default value: 'present'

http_timeout_seconds

Data type: Integer[1]

Timeout for HTTP Telegraf inputs. Might be usefull in huge environments with slower API responses

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: 'toml'

Functions

puppet_operational_dashboards::hosts_with_profile

Type: Puppet Language

Queries PuppetDB for hosts with the specified profile. Used by this module to identify hosts with Puppet Enterprise API endpoints and Telegraf hosts

puppet_operational_dashboards::hosts_with_profile(String $profile)

Queries PuppetDB for hosts with the specified profile. Used by this module to identify hosts with Puppet Enterprise API endpoints and Telegraf hosts

Returns: Array[String] An array of certnames from the query

profile

Data type: String

The full name of the profile to query.

puppet_operational_dashboards::pe_profiles_on_host

Type: Puppet Language

Queries PuppetDB for Puppet Enterprise profile on the node including the class. Used by this module to identify Puppet Enterprise API endpoints on the node.

puppet_operational_dashboards::pe_profiles_on_host()

Queries PuppetDB for Puppet Enterprise profile on the node including the class. Used by this module to identify Puppet Enterprise API endpoints on the node.

Returns: Array[String] An array of PE profiles representing the Puppet server, PDB, and postgres services

Plans

puppet_operational_dashboards::load_metrics

The summary sets the description of the plan that will appear in 'bolt plan show' output. Bolt uses puppet-strings to parse the summary and parameters from the plan.

Parameters

The following parameters are available in the puppet_operational_dashboards::load_metrics plan:

• targets
• support_script_file
• metrics_dir
• dest_dir
• cleanup_metrics
• influxdb_org
• influxdb_bucket
• influxdb_port
• grafana_datasource
• telegraf_token
• token_file
• conf_dir
• retention_rules
• telegraf_process
• token

targets

Data type: TargetSpec

The targets to run on.

support_script_file

Data type: Optional[String]

Path to a support script tarball

Default value: undef

metrics_dir

Data type: Optional[String]

Path to the 'metrics' directory from a PE support script

Default value: undef

dest_dir

Data type: String

Directory to upload $metrics_dir to

Default value: '/tmp'

cleanup_metrics

Data type: String

Whether to delete metrics after processing

Default value: 'true'

influxdb_org

Data type: String

Name of the InfluxDB organization to configure. Defaults to 'puppetlabs'

Default value: 'puppetlabs'

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to configure and query. Defaults to 'puppet_data'

Default value: 'influxdb_puppet'

influxdb_port

Data type: Integer

Port used by the InfluxDB service. Defaults to the value of influxdb::port, or 8086 if unset

Default value: 8086

grafana_datasource

Data type: String

Name of the Grafana datasource. Must match the name of the InfluxDB bucket

Default value: $influxdb_bucket

telegraf_token

Data type: String

Name of the token to retrieve from InfluxDB. Defaults to 'puppet telegraf token'

Default value: 'puppet telegraf token'

token_file

Data type: String

Location on disk of an InfluxDB admin token. This file is written to by the influxdb class during installation and read by the type and providers, as well Deferred functions in this module.

Default value: '/root/.influxdb_token'

conf_dir

Data type: String

Directory to upload Telegraf configuration files to

Default value: '/tmp/telegraf'

retention_rules

Data type: Array[Hash]

Default value:

[{
      'type' => 'expire',
      'everySeconds' => 3456000,
      'shardGroupDurationSeconds' => 604800,
  }]

telegraf_process

Data type: Enum['local', 'remote']

Default value: 'remote'

token

Data type: Optional[String]

Default value: undef

puppet_operational_dashboards::provision_dashboard

A plan to provision a non-SSL operational dashboards node

Parameters

The following parameters are available in the puppet_operational_dashboards::provision_dashboard plan:

• targets

targets

Data type: TargetSpec

The targets to run on.

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v2.3.0 (2024-02-05)

Full Changelog

Added

• Fix collection of postgres metrics on FOSS Puppet #206 (m0dular)
• Fix logic to include pe metrics #204 (m0dular)

v2.2.0 (2023-11-16)

Full Changelog

Added

• telegraf: Update Agent 1.27.0->1.28.2 #197 (bastelfreak)
• Update grafana 8.5.26->8.5.27 #196 (bastelfreak)

Fixed

• Bugfix for importing new file sync storage metrics #200 (m0dular)
• (SUP-4138) Restore missing PCP Connections panel #199 (m0dular)
• (SUP-4225) Deprecate Grafana archive installations #195 (m0dular)
• (SUP-4478) Addition of access details for Grafana Dashboard #193 (Aaronoftheages)

v2.1.0 (2023-09-25)

Full Changelog

Added

• (SUP-3616) Support HTTPS Grafana connections #189 (m0dular)
• README.md: Document more hiera examples #186 (bastelfreak)
• Bump module dependencies #185 (m0dular)
• (SUP-4332) Add lag_bytes to postgres dashboard #184 (m0dular)
• Grafana: Update 8.5.20->8.5.26 #183 (bastelfreak)
• puppet/telegraf: Require 5.x; puppetlabs/stdib: Require 9.x #181 (bastelfreak)
• telegraf: Bump 1.25.3-1->1.27.0-1 #180 (bastelfreak)
• Add state timelines for catalog and function perf #177 (m0dular)

Fixed

• (SUP-4436) Grafana Module Version Change #190 (Aaronoftheages)
• (GH-187) Update grafana_wait.epp template to use grafana_port value #188 (rjd1)
• (#74) collect local PCP metrics #179 (bastelfreak)
• (#74) Fix include_pe_metrics in telegraf class #178 (bastelfreak)

v2.0.0 (2023-05-26)

Full Changelog

Added

• Import sar data files #172 (m0dular)
• (SUP-4220) Add panels for PDB pool usage #171 (m0dular)
• (SUP-4138) Add compiler PCP metrics #168 (m0dular)
• (SUP-4138) Add PCP connections #167 (m0dular)
• Add dashboard and script for v2 system metrics #166 (m0dular)
• Document parameters for internal repositories #165 (m0dular)

Fixed

• Remove selection override from db sizes panel #173 (m0dular)

v1.13.1 (2023-04-27)

Full Changelog

Changed

• (SUP-3952) Remove Puppet 6 as a supported platform #158 (elainemccloskey)

Added

• Allow differentiation between ssl influxdb and puppet ssl connections #161 (tuxmea)
• (SUP-4194) Puppet 8 release prep #159 (elainemccloskey)
• Allow disabling of System Performance dashboard creation #157 (tuxmea)
• telegraf: Update 1.24.3-1->1.25.3-1 #155 (bastelfreak)

Fixed

• Restore missing operational_dashboards tag #154 (m0dular)

v1.13.0 (2023-03-29)

Full Changelog

Fixed

• pe_profiles_on_host: Fix orchestrator support #151 (bastelfreak)

v1.12.0 (2023-03-27)

Full Changelog

Added

• (SUP-4087) Add Orchestrator metrics #148 (m0dular)
• (SUP-4065) Add parameter for group_by interval #146 (m0dular)

Fixed

• Fix null checks in puppetserver import script #149 (m0dular)
• limit apt workaround scope to Debian #145 (vchepkov)

v1.11.0 (2023-02-28)

Full Changelog

Added

• Add influxdb_bucket_retention_rules parameter #141 (SimonHoenscheid)
• update grafana_version to fix CVE-2022-23552 and CVE-2022-39324 #138 (SimonHoenscheid)

Fixed

• Group the total db size by 5m intervals #139 (m0dular)
• Fix JRuby lock wait and held times #137 (m0dular)

v1.10.0 (2023-02-07)

Full Changelog

Added

• Update default version of grafana installed #132 (elainemccloskey)
• (SUP-3459) Add queries for G1GC metrics #124 (m0dular)
• Pass port to InfluxDB resources #118 (m0dular)

Fixed

• Filesync dashboard cleanup #123 (seanmil)
• Ensure consistent config generation order #122 (seanmil)

v1.9.0 (2022-12-02)

Full Changelog

Added

• timeouts for http inputs are now configurable #114 (SimonHoenscheid)

v1.8.0 (2022-11-07)

Full Changelog

Added

• (SUP-3761) Add thread and file descriptor panels #106 (m0dular)
• (SUP-3735) have dashboards autorefresh #103 (MartyEwings)
• mv telegraf agent os-specific params to hiera data #101 (zoojar)
• added insecure_skip_verify param #100 (zoojar)

Fixed

• (SUP-3764) Fix compatability with Telegraf 1.24.3 #109 (m0dular)

v1.7.0 (2022-10-18)

Full Changelog

Added

• Accept a support script tarball for archive metrics ingest #96 (m0dular)

v1.6.0 (2022-10-12)

Full Changelog

Added

• Add file sync client metrics to archive script #91 (m0dular)

Fixed

• Check type of $targets parameter #92 (m0dular)

v1.5.0 (2022-10-11)

Full Changelog

Added

• (SUP-3688) Plans to provision and import metrics #87 (m0dular)
• (SUP-3565) Support Telegraf archive install on EL #75 (m0dular)

v1.4.0 (2022-09-30)

Full Changelog

Added

• (SUP-3675) Remove -H flag from ss command #86 (m0dular)
• Pass use_ssl param to InfluxDB resources #84 (m0dular)

v1.3.0 (2022-09-19)

Full Changelog

Added

• (SUP-3646) Grafana Bump for security vulnerability #79 (MartyEwings)
• SUP-3276 Add system metrics from archives #71 (m0dular)
• (SUP-3431) Add index and toast stats to postgres #70 (m0dular)
• (SUP-3220) Rewrite Puppet server script #68 (m0dular)

Fixed

• README.md: Cleanup trailing whitespace / Fix typo #73 (bastelfreak)
• (SUP-3396) Remove ha_last-sync-succeeded mbeans #72 (m0dular)
• (SUP-3388) Change error handling in PDB script #69 (m0dular)
• (SUP-3403) Fix labels in compile/borrow panel #67 (m0dular)

v1.2.0 (2022-06-10)

Full Changelog

Added

• (SUP-3025) Add spec tests #63 (m0dular)

Fixed

• (SUP-3358) Fix $use_ssl logic across all manifests #62 (m0dular)
• (SUP-3357) Move manage_grafana to dashboard class #61 (m0dular)
• (SUP-3348) Telegraf ssl bugfixes #60 (m0dular)

v1.1.0 (2022-05-27)

Full Changelog

Added

• (SUP-3329) Add metric archive info to ARCHIVES.md #55 (m0dular)
• Add metrics from route-ids #53 (m0dular)
• Add PDB JVM GC panels #51 (m0dular)
• Add panels for Puppet server GC times and counts #50 (m0dular)
• (SUP-3250) Add HA and other PDB panels #48 (m0dular)

Fixed

• (SUP-3319) Refresh service when datasource changes #54 (m0dular)
• Fix queue_depth metric in starlark processor #49 (m0dular)
• Fix panels related to PDB connections #47 (m0dular)

v1.0.0 (2022-05-04)

Full Changelog

Changed

• (SUP-3061) Install class for ent infrastructure agents #36 (MartyEwings)

Added

• Display all http client and function metrics #43 (m0dular)
• Add panels for PDB read and write pools #42 (m0dular)
• (SUP-3243) Add index stats for pe-puppetdb tables #40 (m0dular)
• (SUP-3241) Add in Dashboard documentation #39 (MartyEwings)
• Check for existance of keys in dict #26 (m0dular)

Fixed

• (SUP-3235) Use latest telegraf package on Ubuntu #38 (m0dular)
• make resource ordering specific to install class #37 (MartyEwings)
• (SUP-3228) Fix Ubuntu compatibility issue #35 (MartyEwings)
• (SUP-3201) Check port availability with systemd #33 (m0dular)
• (SUP-3201) Accept any Sensitive value in template #32 (m0dular)
• (SUP-3209) Grant pg_monitor role to telegraf #31 (m0dular)
• (SUP-3201) Make Grafana datasource idempotent #30 (m0dular)
• Fix handling of 'error' entry in dict #28 (m0dular)

v0.2.0 (2022-03-11)

Full Changelog

Added

• Use retrieve_token as a Deferred function #21 (m0dular)

Fixed

• Fix postgres auth for Telegraf agents #19 (m0dular)

v0.1.2 (2022-03-08)

Full Changelog

Fixed

• Fix name #14 (m0dular)

v0.1.1 (2022-03-08)

Full Changelog

Fixed

• Add README #5 (m0dular)

* This Changelog was automatically generated by github_changelog_generator