Internal documentation only
This page has been marked as draft.
New User Guide
This is the documentation template for a new user guide or new section in the Geneos documentation. 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.
Introduction Copied
- Provide context and background information about the topic. Describe:
- What the topic is about
- What is the purpose of the topic
- Briefly describe intended users (if applicable) and the relevance of the topic to its users.
Components Copied
Briefly describe the different features and components of the new topic, if applicable. You can use a diagram, screenshot, Storylane demo, or other graphics to supplement your explanation of the concept.
For example:
Note
Always add an alt text for images.
Prerequisites Copied
- List all required prerequisites for installation and their respective versions.
- If applicable, link topics to existing documentation (e.g., configuration of mappings, setting up a 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.
Deployment Planning Copied
Discuss the planning process for deployment, including the following topics where necessary:
- Identification of the target environment.
- Identification of the stakeholders.
Installation Copied
Describe installation topics in this section. This can include configuration and deployment information. Add the configuration file/s as well. This can be in the form of a YAML file (as shown below) or a downloadable xml or script file the users can run in their machines.
For example:
[Download the ingestion proxy monitoring script](/geneos/downloads/ingestion-proxy-monitoring.xml "Download ingestion proxy monitoring include file").
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.
Configuration Copied
If the topic requires configuration in the Gateway Setup Editor (GSE), it would be helpful for the users to add a screenshot of how it looks like in GSE and what specific fields must be completed.
For example:
Users will need to configure the following to authenticate with the database:
database > enabled Copied
This Boolean setting specifies whether message database logging is enabled. This flag allows the feature to be disabled without un-configuring the database details. Mandatory: Yes
database > type > mysql/mariadb Copied
This setting specifies the MySQL/MariaDB connection details. Mandatory: Yes - if the database setting has been specified.
| Setting | Description |
|---|---|
| Server Name | The MySQL/MariaDB server hostname or IP address. Mandatory: Yes |
| Database Name | The FIX Analyser 2 database instance name as hosted by the MySQL/MariaDB server. Mandatory: Yes |
| Port | MySQL/MariaDB server listen port, defaults to 3306. Mandatory: No |
Procedure Copied
A numbered list of items can also be added in the documentation if the user needs to follow a certain set of steps (for example, related to topics on deployment, testing, or backup).
Note
Words that refer to UI-specific elements must be written in bold format.
- Open the Gateway Setup Editor.
- In the Navigation panel, click Includes to create a new file.
- Enter the location of the file to include in the Location field.
- Update the Priority field. This can be any value except
1. If you input a priority of1, the returns an error.- Expand the file location in the Include section.
- Select Click to load.
- Click Yes to load the new include file and save your setup.
Success
Have the steps been followed correctly? Add a success message that they can expect to see in the system.
Error
Add any error messages that they can expect to see in the system if the steps have not been followed correctly.
Add sample keys, scripts, configuration, or code that may be relevant for the user. For example:
keyStore=config/keystore.db
trustStore=config/keystore.db
keyStorePassword=ab987c
trustStorePassword=ab987c
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.