Skip to content

Latest commit

 

History

History
229 lines (179 loc) · 9.85 KB

configure.md

File metadata and controls

229 lines (179 loc) · 9.85 KB

Configure Flex

Flex integrations are code-less: They only require that you write configuration files for each integration as YAML files.

Configurations can go embedded in the Infrastructure agent configuration file, or live as stand-alone config files that you can test separately and link from the main integrations config file. What approach to follow is up to you.

Add your configuration to integrations.d

Since it comes bundled with the Infrastructure agent, Flex's configuration must be stored as YAML in the same folder as the rest of on-host integrations:

  • Linux: /etc/newrelic-infra/integrations.d
  • Windows: C:\Program Files\New Relic\newrelic-infra\integrations.d\

The main section of the integrations config file is used by the Infrastructure agent to execute Flex like any other integration; you can add your Flex configuration under config.

For example, /etc/newrelic-infra/integrations.d/my-flex-config.yml could contain the following:

integrations:
  - name: nri-flex # We're telling the Infra agent to run Flex
    interval: 60s
    timeout: 5s
    config: # Flex configuration starts here!
      name: example
      apis:
        - event_type: ExampleSample
          url: https://my-host:8443/admin/metrics.json
  • On-Host Integration Configuration: the first five lines are read by the agent to execute the nri-flex binary every 60 seconds, canceling the execution if it lasts more than 5 seconds. Refer to Integration configuration file specifications for more details about the contents of the on-host integrations configuration file.
  • Flex configuration: contains the actions to be taken using data sources APIs, such as the url API.

To get a quick, first picture of a Flex configuration file, you can start following our basic, step-by-step tutorial or check existing config files under /examples.

Link to a separate configuration file

You can store the Flex configuration in a separate YAML file (for example, after developing and testing a config file) and reference it by replacing config with config_template_path property, which contains the path of the Flex config file.

This way, the equivalent of /etc/newrelic-infra/integrations.d/my-flex-config.yml from the previous section would contain:

integrations:
  - name: nri-flex
    interval: 60s
    timeout: 5s
    config_template_path: /path/to/flex/integration.yml # Reference to a separate Flex config file

/path/to/flex/integration.yml would contain the contents that previously were inside the config section:

name: example
apis:
  - event_type: ExampleSample
    url: https://my-host:8443/admin/metrics.json

Configuration schema

The following schema describes the overall structure of a Flex configuration.

+----------------------+
| name                 |
| global?              |
| +--------------+     |
| | <properties> |     |   Suffixes:
| +--------------|     |       ? optional
| custom_attributes?   |       * multiple repetitions 
| +----------------+   |
| | <key>: <value> | * |
| +----------------+   |
| apis                 |
| +---------------+    |
| |  name?        |    |
| |  event_type?  | *  |
| |  <api>        |    |
| |  <functions>* |    |
| +---------------+    |
+----------------------+

name

The name of the Flex configuration. It should be something short and meaningful.

global

Set of global properties that apply to the overall file. The aim of this section is to avoid repeating some values (like URLs or user credentials).

Example:

global:
  base_url: http://localhost:9200/
  user: elastic
  pass: 3l4st1c
  headers:
    accept: application/json

These are all the possible global properties:

Property Description
base_url Base URL. See specifying a common base URL
user Username for APIs that require user and password authentication
password Password for APIs that require user and password authentication
pass_phrase Pass phrase for encrypte password properties
proxy Proxy URL for APIs whose connections require it
timeout Timeout for the API connections, in milliseconds
headers Key-value map of headers for the HTTP/HTTPS connections
tls_config TLS configuration. See configuring your HTTPS connections
ssh_pem_file Path to PEM file to enable SSH authentication
JMX See JMX (experimental)

apis

The apis section allows you to define multiple entries for data acquisition and processing. Each entry must have a name or event_type, which is used to name the event type in New Relic:

  • event_type provides a name for each sample, which is used as table name for querying the metrics in the New Relic UI. event_type usually have names like MySQLSample, MyRemoteSample, FolderSample, etc.
  • If event_type is not defined and name is, the submitted event type is name with the Sample prefix concatenated.
    • For example, name: FolderSize would make Flex to create events named event_type: FolderSizeSample.

In addition to the fields that define the name of the sample, each apis entry requires the type of API to parse data from, and, optionally, a list of functions for processing the data coming from the API.

Cache

Flex by default stores the result of an API execution in it's internal cache. You can then use this cache as input to another API for further processing.

For example, consider a service that returns the following payload

{
    "id": "eca0338f4ea31566",
    "leaderInfo": {
        "leader": "8a69d5f6b7814500",
        "startTime": "2014-10-24T13:15:51.186620747-07:00",
        "uptime": "10m59.322358947s",
        "abc": {
            "def": 123,
            "hij": 234
        }
    },
    "name": "node3"
}

as a result of executing the following url API:

name: example
apis:
    - name: someService
      url: http://some-service.com/status

As we want to process it in another API, we use the cache function. Note that the cache key is the URL because it's an url API:

name: example
apis:
    - name: status
      url: http://some-service.com/status
    - name: otherStatus
      cache: http://some-service.com/status
      strip_keys:
          - id
          - name

With a commands API, you should use the name of the API instead:

name: example
apis:
    - name: status
      commands:
          # assume that this file contains the same json payload showed above the beginning
          - run: cat /var/some/file
    - name: otherStatus
      cache: status
      strip_keys:
          - id
          - name

Custom attributes

With Flex you can add your own custom attributes to samples. Add any custom attribute using key-value pairs under the global directive, and at the API level by declaring an array named custom_attributes.

custom_attributes:
  greeting: hello

Custom attributes can be defined nearly anywhere in your configuration. For example, under global, or api, or further nested under each command. Attributes defined at the lowest level take precedence.

Custom attributes defined at the global level are added to all samples, while custom attributes defined at the API level are added only at the level of the API where they are defined.

Environment variables

You can inject values for environment variables anywhere in a Flex config file. To inject the value for an environment variable, use a double dollar sign before the name of the variable (for example $$MY_ENVIRONMENT_VAR).

Configuration example

Here's an example of a Flex configuration embedded in the main integrations configuration file:

integrations:                                    # OHI configuration starts here  
  - name: nri-flex                               # OHI to be executed by the Agent
    config:                                      # OHI configuration to be parsed by Flex
      # Actual Flex configuration starts here
      name: linuxDirectorySize                   # Flex configuration name
      apis:                                       
        - name: DirectorySize                    # Event type will be DirectorySizeSample
          commands:                              # Selecting the API `commands`
            - run: du -c $$DIR                   # Running a shell command
              split: horizontal                  # Post-processing function: split horizontally
              set_header: [dirSizeBytes,dirName] # Names for the headers of the table resulting from split
              regex_match: true                  # Splits horizontally matching a regular expression
              split_by: (\d+)\s+(.*)             # Captures the regexpes between parentheses as the headers above