Example: Configuring collectd

In this example, we'll configure collectd to push metrics to the cloud agent receiver via collectd's write_http plugin. 

Note:

The examples shown in this section are only applicable to collectd version 5.5 and above.

The generic metric collector's receiver listens to requests sent to https://<host>:<port>/emd/receiver/gmc. Here, <port> is same port shown in the URL returned by running the omcli status agent command on the cloud agent host.

On the collectd side, the same information is provided in its configuration file, as shown in the following example.

write_http Plugin Configuration

<Plugin write_http>
         <Node "omc">
           URL "https://127.0.0.1:1899/emd/receiver/gmc"
           Format "JSON"
           StoreRates true
           VerifyPeer false
         </Node>
</Plugin>

By setting StoreRates to true, collectd is configured to send rates rather than counter values to Oracle Management Cloud. The POST method is used to send and receive metrics.

The collectdctl control interface communicates with the collectd agent process using UNIX domain sockets. To have the cloud agent monitor collectd, the unixsock plugin is enabled and configured as shown in unixsock Plugin Configuration.

Note:

If collectd is remotely located relative to the cloud agent host, specify the cloud agent host name instead of the loop-back address of 127.0.0.1.

unixsock Plugin Configuration

<Plugin unixsock>
        SocketFile "/opt/collectd/var/run/collectd-unixsock"
        SocketGroup "collectd"
        SocketPerms "0660"
        DeleteSocket false
</Plugin>

Note:

unixsock plugin configuration (along with adding an agent user to the SocketGroup) is only required if collectd is co-located with cloud agent and should be monitored by it.

As shown in the configuration above, UNIX domain sockets use file-based permissions, unlike internet sockets. In case the cloud agent user is not the same as the user running the collectd process, you need to ensure that the cloud agent user has both read and write (06) permission on the socket. One way to ensure this is by adding the cloud agent user to SocketGroup ("collectd" in the above example).

The cloud agent user is the user who started the cloud agent. You can determine who the cloud agent user is by running the following command:

omcli status agent

If the group specified for SocketGroup does not exist on the host, you'll need to add one as shown below.

$ sudo /usr/sbin/groupadd collectd

Add a Cloud Agent User to a SocketGroup

In the following example, you are adding a cloud agent to SocketGroup in collectd.

$ sudo /usr/sbin/usermod -a -G collectd <cloud agent user name>

With group permissions in effect, the cloud agent user will be able to run collectdctl commands that communicate with collectd agent.

Additionally, to protect the receiver URI, a new credential with username and password can be added to the cloud agent using the omcli command line interface.

Add HTTP Basic Authentication Credentials (Optional)

$ omcli add_credentials agent -credential_file http_receiver_auth.json

Example content for the http_receiver_auth.json is shown below.

[
  { "entity":"Lama.mycompany.com:1899",
    "name":"omc-receiver-cred",
    "type":"HttpReceiver-Auth",
    "globalName":"HttpReceiver.basic",
    "description":"Internal authorization for the HTTP receiver",
    "properties":[ { "name":"username", "value":"CLEAR[scott]" },
                   { "name":"password", "value":"CLEAR[tiger]" } ]
 }
]

Here, the cloud agent entity is specified in "<type>.<name>" format (using a period (.) as a separator) where the <name> includes the agent's listening port. The properties username and password are set to scott and tiger respectively. The sender will be required to authenticate with these credentials.

The same username and password are then made known to collectd's write_http plugin by adding User and Password fields to its configuration as shown in the next section.

write_http Plugin Configuration for HTTP Basic Authentication (Optional)

<Plugin write_http>
         <Node "omc">
           URL "https://127.0.0.1:1899/emd/receiver/gmc"
           Format "JSON"
           StoreRates true
           VerifyPeer false
           User "scott"
           Password "tiger"
         </Node>
</Plugin>