Skip to content

Latest commit

 

History

History
308 lines (208 loc) · 7.74 KB

REFERENCE.md

File metadata and controls

308 lines (208 loc) · 7.74 KB
Raw

Reference

Table of Contents

Classes

Public Classes

  • promtail: promtail's main interface. All interactions should be with this class.

Private Classes

  • promtail::config: Creates files and folders associated with promtail's config
  • promtail::install: Installs promtail
  • promtail::service: Creates a service defintion for promtail

Functions

Classes

promtail

promtail's main interface. All interactions should be with this class. The promtail module is intended to install and configure Grafana's promtail tool for shipping logs to Loki.

Examples

include promtail
Sample of defining within a profile
class { 'promtail':
  clients_config_hash   => $clients_config_hash,
  positions_config_hash => $positions_config_hash,
  scrape_configs_hash   => $_real_scrape_configs_hash,
  password_file_content => $sensitive_password_file_content,
  password_file_path    => $password_file_path,
  service_ensure        => $service_ensure,
  server_config_hash    => $server_config_hash,
  target_config_hash    => $target_config_hash,
  bin_dir               => $bin_dir,
  checksum              => $checksum,
  version               => $version,
}
Settings in a Hiera file
---
promtail::password_file_path: '/etc/promtail/.gc_pw'
promtail::password_file_content: ENC[PKCS7,MIIBasdfasdfasdfasdfasdfasdf==]
promtail::server_config_hash:
  server:
    http_listen_port: 9274
    grpc_listen_port: 0
promtail::clients_config_hash:
  clients:
    - url: 'https://logs-us-west1.grafana.net/api/prom/push'
      basic_auth:
        username: '1234'
        password_file: '/etc/promtail/.gc_pw'
promtail::positions_config_hash:
  positions:
    filename: /tmp/positions.yaml
promtail::scrape_configs_hash:
  scrape_configs:
    - job_name: journal
      journal:
        max_age: 12h
        labels:
          job: systemd-journal
          host: "%{facts.networking.fqdn}"
      relabel_configs:
        - source_labels:
            - '__journal__systemd_unit'
          target_label: 'unit'
        - source_labels:
            - 'unit'
          regex: "session-(.*)"
          action: replace
          replacement: 'pam-session'
          target_label: 'unit'
Merging scrape configs in Hiera
class profile::logging::promtail {
  $_real_scrape_configs_hash = lookup('promtail_scrape_configs_hash', {merge => 'deep'})
  class { 'promtail':
    scrape_configs_hash => $_real_scrape_configs_hash,
  }
}

Parameters

The following parameters are available in the promtail class:

service_enable

Data type: Boolean

The value passed to the service resource's enable parameter for promtail's service

service_ensure

Data type: Enum['running', 'stopped']

The value passed to the service resource's ensure parameter for promtail's service

clients_config_hash

Data type: Hash

Describes how Promtail connects to multiple instances of Loki, sending logs to each. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

positions_config_hash

Data type: Hash

Describes how to save read file offsets to disk. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

scrape_configs_hash

Data type: Hash

Each scrape_config block configures how Promtail can scrape logs from a series of targets using a specified discovery method. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

bin_dir

Data type: Stdlib::Absolutepath

The directory in which to create a symlink to the promtail binary

checksum

Data type: String[1]

The checksum of the promtail binary. Note: each platform has its own checksum. Values can be found with each release on GitHub

version

Data type: String[1]

The version as listed on the GitHub release page See https://github.com/grafana/loki/releases for a list

server_config_hash

Data type: Optional[Hash]

Configures Promtail's behavior as an HTTP server. Defaults will be used if this block is omitted. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

Default value: undef

target_config_hash

Data type: Optional[Hash]

Configures how tailed targets will be watched. Defaults will be used if this block is omitted. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

Default value: undef

password_file_path

Data type: Optional[Stdlib::Absolutepath]

The fully qualified path to the file containing the password used for basic auth

Default value: undef

password_file_content

Data type: Optional[Sensitive[String[1]]]

The value to be placed in the password file. This value is cast to Sensitive via lookup_options defined in data/common.yaml

Default value: undef

source_url

Data type: Stdlib::HTTPUrl

The URL from which promtail packages can be downloaded

Default value: 'https://github.com/grafana/loki/releases/download'

Functions

promtail::strip_yaml_header

Type: Ruby 4.x API

A function to strip the --- from the beginning of a string

Examples

concat::fragment { 'server_config_hash':
  target  => $config_file,
  content => $promtail::server_config_hash.promtail::to_yaml.promtail::strip_yaml_header,
  order   => '10',
}

promtail::strip_yaml_header(String $yaml_string)

A function to strip the --- from the beginning of a string

Returns: String Returns the string with the leading header stripped off

Examples
concat::fragment { 'server_config_hash':
  target  => $config_file,
  content => $promtail::server_config_hash.promtail::to_yaml.promtail::strip_yaml_header,
  order   => '10',
}
yaml_string

Data type: String

A string that may start with the ---'s used to denote a YAML file

promtail::to_yaml

Type: Ruby 4.x API

A function to convert a hash into yaml for the promtail config

Examples

promtail::to_yaml($promtail::config_hash)

promtail::to_yaml(Hash $config_hash)

A function to convert a hash into yaml for the promtail config

Returns: String Returns the YAML version of the hash as a string

Examples
promtail::to_yaml($promtail::config_hash)
config_hash

Data type: Hash

A Puppet hash to be converted into YAML