Internal documentation only
This page has been marked as draft.
Geneos Collection Agent Plugin User Guide
This is the documentation template for a new Collection Agent plugin. Instructions or information about each section of this template are written in plain text like this. You may tweak the sections of the template as necessary.
Overview Copied
- Provide context and background information about the plugin.
- Briefly describe how the plugin collects data (what collectors does the plugin use) or how the plugin works.
- Briefly describe intended users (if applicable).
Prerequisites Copied
Geneos environment Copied
- List all required versions of Geneos components (e.g., Collection Agent, Gateway, and Netprobe).
- If applicable, link topics to existing documentation (e.g., configuration of mappings, setting up the plugin). These can be documentation within the same topic or documentation from a different topic that may contain the same information.
- Add a link to the Resources page if binaries are required to be downloaded.
Set up your Collection Agent plugin Copied
List down detailed steps/procedures for setting up the CA plugin. Screenshots/demos can complement these topics. For example:
Set up your collector in the Gateway Setup Editor by adding the following configuration in Dynamic Entities > Collectors. For more information, see Collectors in Dynamic Entities.
Configuration reference Copied
Add sample configuration file/s. This is usually in YAML format.
Below is an example YAML file which may require some changes for your project’s configuration:
collectors:
- type: plugin
className: FluentdForwardCollector
# Required. Port on which to receive TCP (+ TLS/SSL) messages and UDP heartbeats.
port: 24224
# Acceptor thread pool size (default = 1)
acceptorThreadPoolSize: 1
# Worker thread pool size (default = 1)
workerThreadPoolSize: 1
# Optional TLS configuration.
tlsConfig:
# Required when tlsConfig is configured.
# Server key - required to enable TLS
keyFile: /path/to/private_key.pem
# Required when tlsConfig is configured.
# Server certificate - required to enable TLS.
certFile: /path/to/cert_file.pem
# Client trust chain - only required for client authentication.
trustChainFile: /path/to/trust_chain.pem
# Required. Name of event data key to use as the log event name.
nameKey: ident
# Optional tag mapping.
# Every batch of messages contains a tag which may be mapped into log events.
# Values:
# - none (default): ignored the tag
# - namespace: tag value is appended to the log event namespace
# - name: tag value is prepended to the log event name
# - dimension: tag value is added as a dimension
tagMapping: none
# Optional. Name of event data key to use to extract the log event message.
# Default is 'message'.
messageKey: message
# Optional. Event data keys to use as dimension keys.
# The key here is used as the search key in the event data and value (if any)
# is inserted as a dimension with key mapped as specified.
dimensions:
# If event data contains {host=www.myhost.com} then it is mapped to a dimension {host.name=www.myhost.com}.
host: host.name
pid: pid.number
# Optional. Event data key and optional mappings to extract severity from the event data.
severityMapping:
# Event data key to use to extract severity value.
key: level
# Optional severity mapping value in case source system uses different values.
# Supported target values are: [none, trace, debug, info, warn, error, critical]
values:
fatal: critical
- Add more sample configuration files for specific scenarios where further configuration may be necessary.
- List down and describe metrics, data types (for example, using this format,
String,Number,DateTime), settings, and other parameters as needed.
Note
Notes can also be added within the document for any supplemental information. This can be in different formats. See relevant resources.
Configure your mappings Copied
- Add mapping configuration instructions as needed. Link this to existing documentation on mapping configuration.
- Indicate here if there is a mapping template available for download or included in the Gateway package.
- See example below:
To show metrics and events in Geneos, dynamic mappings must be configured and attached to the Netprobe receiving the data from the Collection Agent. Select one of the options listed below to configure your dynamic mappings.
Choose a built in mapping in **Dynamic Entities** > **Mapping** or set up a custom mapping in **Dynamic Entities** > **Mapping**. For more information, see the [Mapping and mapping group in Dynamic Entities](__tcproject__/docs/geneos/current/processing/configuration/dynamic_entities/index.html#mapping-and-mapping-group) documentation.
Sample mappings are included in the Gateway package in `templates/vmware_mapping.xml`. This can be added as an include file in your Gateway.
Sample dataview Copied
Add a sample dataview if available.
You can also describe the headlines and columns in the dataview.
Headline legend Copied
| Headline | Description |
|---|---|
| Row 1 | Row 1 |
| Row 2 | Row 2 |
| Row 3 | Row 3 |
Table legend Copied
| Column | Description |
|---|---|
| Row 1 | Row 1 |
| Row 2 | Row 2 |
| Row 3 | Row 3 |
Sample metrics table Copied
Documentation for Collection Agent plugins normally include a list of metrics that is being measured by the plugin.
For example, the table below shows a set of metrics collected by the Kubernetes plugin.
| Metric | Type | Unit | Dimensions | Description |
|---|---|---|---|---|
| kube_resource_quota_hard | gauge | millicores/bytes/none | namespace, quota, resource | Configured hard limit. |
| kube_resource_quota_used | gauge | millicores/bytes/none | namespace, quota, resource | Quota used amount. |
| kube_resource_quota_used_percent | gauge | % | namespace, quota, resource | Quota used percent. |
Post-deployment activities / Troubleshooting Copied
Describe here activities that the users need to complete after deployment. This section can also talk about common troubleshooting issues and detailed steps on how to resolve them. Screenshots/demos can complement these topics.
Problem Copied
Describe how the issue or error happened. If applicable, you can include a screenshot of the error.
Cause Copied
Answer the following questions:
- Why does this issue/error occur? If there are multiple causes, consider listing them.
- At what circumstances does it usually occur?
- What are the symptoms of this issue/error?
Solution Copied
Detail the steps on how to solve the issue/error. If there is more than one solution, consider listing them.
- Solution 1
- Solution 2
- Solution 3
You can add diagrams, screenshots, and code samples to make each step clearer. In addition and if applicable, use notes, warnings, or tips to highlight any important information that users must know about.
Relevant resources Copied
For more information about writing in markdown, refer to the following resources:
Add additional topics as necessary to provide more information for the users. This can be in the form of screenshots of sample dataviews or links to external documentation relevant to the plugin. Refer to existing documentation on the docs website for further reference.