Observability Data Connector

Table of Contents

• What is the Observability Data Connector module?
• Prerequisites
• Install and configure the Observability Data Connector
  • Install the module
  • Configure the module
  • Configure a filter for metrics
  • Set the exporter port
• Run the module
• Test the module
• Troubleshooting and support
  • Verify the module installation
  • Detect network and configuration issues
  • Review log files
  • Request support

What is the Observability Data Connector module?

The Observability Data Connector module is a Prometheus metrics exporter for Puppet Enterprise Advanced. With the Observability Data Connector, you can export Puppet® transaction and report metrics in Prometheus format. In this way, you can track events in real time to identify and resolve possible issues and optimize the management of your infrastructure.

Important: This document includes references to a third-party product, Prometheus. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Prometheus, see What is Prometheus?

Prerequisites

• Puppet Enterprise® 2023.7.1 or later.
• The Observability Data Connector, which is available to Puppet Enterprise Advanced customers as premium content on Puppet Forge. See puppet_data_connector.

Install and configure the Observability Data Connector

Before you can start using the module, you must install and configure it.

Install the module

Install the module by taking one of the following actions:

• Run the following command: puppet module install puppetlabs-puppet_data_connector
• Install the module by using Code Manager. For details, see Managing code with Code Manager.

Configure the module

You must classify the Observability Data Connector in the Puppet Enterprise (PE) console.

1. In the PE console, navigate to Node groups and expand PE Infrastructure.
2. Select the node group that you want to monitor and navigate to the Classes tab.
3. Click Refresh to ensure that the puppet_data_connector class is loaded.
4. Add a new class: puppet_data_connector.
5. Under Parameter , specify the dropzone parameter to configure the drop zone for the metrics.
6. Commit your changes and run Puppet on the node group.

Configure a filter for metrics (optional)

The Observability Data Connector can filter metrics to provide a concise view of your data. The filter is a blocklist.

Caution: Any filter parameter that you define removes data from the data set.

When you apply a filter, you can specify attributes from Puppet reports. For a list of attributes, see Report format. You can use the metric_filter parameter for top-level metrics, such as time, resources, events, and changes. You can use the events_filter and resources_filter parameters to specify the attributes listed for events and resources.

You can apply a filter by using a code block, as shown in the following example:

class { 'puppet_data_connector':
  dropzone         => '/opt/puppetlabs/puppet/prometheus_dropzone',
  metric_filter    => [“changes”, “events”],
  events_filter    => [“success”],
  resources_filter => [“failed”],
}

However, to streamline the process, apply the filter in the Puppet Enterprise console, as shown in this example:

Set the exporter port (optional)

The default port for the Observability Data Connector exporter is 9100. However, you can specify any valid port number.

To set the port number, add the puppet_data_connector::prometheus_exporter::port parameter to the configuration data for the primary server and the compilers configured with the puppet_data_connector class.

In the following example, an exporter port of 9500 is set:

For detailed instructions about using the Puppet Enterprise console for classification, see Grouping and classifying nodes).

Run the module

The Observability Data Connector runs automatically during catalog compilation, and the latest data is generated in Prometheus format.

You can also manually start the module by running the following command:

puppet agent -t

Test the module

You can test the module by accessing a URL that includes the fully qualified domain name for Puppet Enterprise and the port. The HTTP GET method then returns raw metrics.

Specify the URL as shown in the following example, where 9100 is the port, and <puppet_enterprise_fqdn> must be replaced with the fully qualified domain name:

http://<puppet_enterprise_fqdn>:9100/metrics

Troubleshooting and support

If the Observability Data Connector does not work as expected, the cause might be network issues or incorrectly configured Prometheus related collectors. For troubleshooting and support tips, see the following sections.

Verify the module installation

Ensure that the module is correctly installed in your module path. Run the following command:

puppet module list

Detect network and configuration issues

The configured port must be visible on the network.

Review log files

All logging information for the Observability Data Connector can be found in the following file:

/var/log/puppetlabs/puppetserver/puppetserver.log

Request support

Puppet offers two types of support: Premium and Standard. The details vary based on the purchased support package. For a detailed description of the Premium and Standard service-level agreements, see Puppet, Inc. Support and Maintenance Services Terms.

This module is licensed for Puppet Enterprise Advanced.

© 2024 Puppet, Inc., a Perforce company. All rights reserved.

Puppet and other identified trademarks are the property of Puppet, Inc., Perforce Software, Inc., or an affiliate. Such trademarks are claimed and/or registered in the U.S. and other countries and regions. All third-party trademarks are the property of their respective holders. References to third-party trademarks do not imply endorsement or sponsorship of any products or services by the trademark holder. Contact Puppet, Inc., for further details.

Reference

Table of Contents

Classes

Public Classes

• puppet_data_connector: This class manages the Puppet Data Connector.

Private Classes

• puppet_data_connector::prometheus_exporter: Subclass to configure the Prometheus node_exporter.

Data types

• Puppet_Data_Connector::Uri: A URI that can be used to download the Prometheus node_exporter package.

Classes

puppet_data_connector

Configuration and installation of the Puppet Data Connector report processor and Prometheus node_exporter.

Examples

include puppet_data_connector

Parameters

The following parameters are available in the puppet_data_connector class:

• dropzone
• disabled
• stale_time
• metric_filter
• events_filter
• resources_filter

dropzone

Data type: String

Absolute path to dropzone directory. Note: This module creates and manages the dropzone directory.

disabled

Data type: Optional[Boolean]

When 'true', removes report processor settings from puppet.conf.

Default value: false

stale_time

Data type: Optional[Integer]

Number of days without report data, after which a file in the dropzone is considered stale.

Default value: undef

metric_filter

Data type:

Optional[Array[Enum[
        'changes',
        'events',
        'resources',
  'time']]]

A filter to exclude metric types from collection.

Default value: undef

events_filter

Data type:

Optional[Array[Enum[
        'success',
        'failure',
        'audit',
        'noop',
  'total']]]

A filter to exclude certain event types from collection.

Default value: undef

resources_filter

Data type:

Optional[Array[Enum[
        'failed',
        'out_of_sync',
        'changed',
        'total',
        'skipped',
        'failed_to_restart',
        'restarted',
        'scheduled',
  'corrective_change']]]

A filter to exclude certain resource statuses from collection.

Default value: undef

Data types

Puppet_Data_Connector::Uri

A URI that can be used to download the Prometheus node_exporter package.

Alias of Variant[Stdlib::Filesource, Stdlib::HTTPUrl, Stdlib::HTTPSUrl, Pattern[/^s3:\/\//], Pattern[/^gs:\/\//]]

Changelog

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.

v1.0.1 - 2025-06-05

Full Changelog

Fixed

• Updated image links in the README.
• Updated the name in the README to Observability Data Connector.

v1.0.0 - 2024-09-20

Full Changelog

Added

• Converts Puppet Report Metrics to prometheus format.
• Prometheus data is made available with a node_exporter.
• Metrics can be filtered.
• The node_exporter port can be set. It is defaulted to 9100.