Installing and Configuring Agents

You need to perform the following installation instructions for Foglight for Atlas MongoDB in the specified order given below:

  1. Setting Up
  2. Installing the Cartridge
  3. Creating Agents
  4. Agent Properties
  5. Upgrading Agents

Configuring the Atlas MongoDB Setup

You need to configure the Foglight for Atlas MongoDB agent with an API key, database user, and password. Each agent is limited to monitoring the organization associated with its API key.

Creating an API Key

To create an API key:

  1. Log in to the Atlas User Interface.
  2. Ensure that the desired organization is selected.
  3. Click Access Manager at the top of the screen.
  4. Select Organization Access.
  5. Ensure Organization Owner is selected under Organization Permissions.

    Copy the Public Key (username) and Private Key (password) to use later when setting up the agent.

  6. Click Add Access List Entry and enter the IP address of the Foglight Agent Manager, or a CIDR block that contains the Foglight Agent Manager’s address.
  7. Click Done.

The API key gets created.

Creating a Database User

Repeat the following steps on the Atlas User Interface for each cluster that you would like to monitor directly at the database level. Perform the following steps for each cluster to directly monitor at the database level.

Click Projects at the top of the left pane and then select the project name from the list of projects.

To enable network access from the Foglight Agent Manager:

  1. Click Network Access in the left pane.
  2. Under IP Access List, click ADD IP ADDRESS.
  3. In the Access List Entry field, enter the IP address of the Foglight Agent Manager, or a CIDR block that contains the address of the Foglight Agent Manager. Set an optional description. For example, “Foglight Agent Manager”.
  4. Click Confirm.

    Do not click the toggle to make the entry temporary.

The database user must have the ‘clusterMonitor’ and ‘readAnyDatabase’ roles. To enable monitoring of users and roles, the user must also have the custom permissions listed below.

To create a database user without the ability to monitor users or roles:

  1. Click Database Access in the left pane.
  2. Under Database Users click ADD NEW DATABASE USER.
  3. Select Password under Authentication Method.
  4. Set a new username and password, and save them for later use when setting up the agent.
  5. Click Built-in Role dropdown and select Atlas admin.
  6. Click Add User. The user gets created.

To create a user with more precise privileges:

  1. Click Database Access in the left pane.
  2. Click Custom Roles.
  3. Click ADD NEW CUSTOM ROLE.
  4. Enter a name for the custom role.
  5. Under the Action or Role dropdown, expand Global Actions and Roles and Built-In Roles.
  6. Select readAnyDatabase and clusterMonitor.
  7. Click Add Custom Role.
  8. Follow steps 1–4 of the previous procedure mentioned above.
  9. Under Custom Roles, click Add Custom Role.
  10. From the drop-down, select the rule created in step 7.
  11. Click Add User.

Use an existing database user to grant the user privileges to monitor users and roles over a database connection.

  1. Connect to the cluster, over mongosh or MongoDB Compass, as a user that has the grantRole permission on the admin database.
  2. Execute the following code. Be sure to change the username from foglightUser to the username set in the user creation steps above.
db.getSiblingDB('admin').createRole({
    role: 'viewAllUsersAndRoles',
    privileges: [{ resource: { db: '', collection: '' }, actions: ['viewUser', 'viewRole'] }],
    roles: []
})
db.getSiblingDB('admin').grantRolesToUser('foglightAgent', ['viewAllUsersAndRoles'])

Installing the Cartridge

To install the cartridge for the first time:

  1. Open the Foglight Web Console.
  2. From the left navigation pane, select Administration > Cartridges > Cartridge Inventory. The Cartridge Inventory screen appears. For more information on agents, refer to the Foglight User Guide.
  3. Browse to the location of the Foglight for Atlas cartridge (.car) file and click Install Cartridge to load it. Select the Enable on Install checkbox.
  4. Once the installation on the Foglight Management Server is complete, the AtlasMongoDBAgent Cartridge appears in the list of installed cartridge.

Creating Agents

The Agent Status dashboard can be used to create new agents and configure and manage existing agents. To access the page from the navigation pane, select Administration > Agents > Agent Status.

To create a new agent instance:

  1. Deploy the Atlas agent package to the FglAM hosting the agent before creating an agent. You can click Deploy Agent Package on the Agent Status or Agent Managers page to perform this.
  2. Click Create Agent and follow the instructions on the wizard:
    a. Host Selector - Select the Agent Manager on which the agent should run. Considerations for this may include physical or virtual locality to the monitored instance, allocated resources, or grouping with other agents of the same type or monitored environment.
    b. Agent Type and Instance Name – Select the AtlasMongoDBAgent type. Then, select the Specify Name radio button and enter the agent instance name to be created in the Name field. This is representative of the database instance that the agent will monitor, rather than canonical.
    c. Summary – Click Finish.
  3. After the agent is created, select the checkbox next to its name.
  4. Click Edit Properties.
  5. Select Modify the default properties for this agent.
  6. Edit the agent properties for the agent instance
  7. Click Activate.

To modify the properties of an existing agent, skip to step 3, deactivate the agent, update the configuration, and then reactivate it.

Configuring Agent Properties

For new agents, the default values can be accepted for most fields. The sections that must be configured for all agents are Atlas Connection and Database Connections.

Setting up the Atlas connection (mandatory)

For Atlas Connection, enter the API Key Username and API Key Password. Refer to API Key for instructions on how to set up the API key. Leave Disable Certificate Authentication? at its default value of false.

Setting up the database connection (mandatory)

For Database Connections:

  1. Ensure that the default DBConnectionsList is selected.
  2. Click Clone and assign a name to the new list that is relevant to the agent.
  3. Click Edit (the newly cloned list should already be selected).
  4. Click Add Row once for each cluster that is to be monitored at the database level.
  5. For each row, enter the required fields Cluster, Username, and Password. Refer to Database User for instructions on how to set up a user. Set the Project field only if there are two clusters with the same name on different clusters within the organization. Leave the remaining fields at their default values.
  6. Click Save.

Setting Collection Periods (optional)

The Collection Period fields in the agent properties are used to set the sample frequencies. Before you modify the periods for an agent, make a copy of the default period list and modify the copy.

  • Access - Period for collecting access data. Default value is 300 seconds.
  • Access Log - Period for collecting access log data. Default value is 300 seconds.
  • Alert - Period for . Default value is 60 seconds.
  • Availability - Period for . Default value is 60 seconds.
  • Billing - Period for . Default value is 300 seconds.
  • Billing Detail - Period for . Default value is 3600 seconds.
  • Cloud - Period for . Default value is 300 seconds.
  • Cluster - Period for . Default value is 300 seconds.
  • Encryption - Period for . Default value is 300 seconds.
  • Measurement Database - Period for . Default value is 300 seconds.
  • Measurement Disk - Period for . Default value is 300 seconds.
  • Measurement Host - Period for . Default value is 300 seconds.
  • Measurement Search - Period for . Default value is 300 seconds.
  • Organization - Period for . Default value is 300 seconds.
  • Private Endpoint - Period for . Default value is 300 seconds.
  • Process - Period for . Default value is 300 seconds.
  • Project - Period for . Default value is 300 seconds.
  • Queries - Period for . Default value is 300 seconds.
  • Serverless - Period for . Default value is 300 seconds.
  • Team - Period for . Default value is 300 seconds.
  • User - Period for . Default value is 300 seconds.
  • Connection Status - Period for MongoDB availability monitoring. Default value is 30 seconds.
  • Server - Period for MongoDB server monitoring. Default value is 300 seconds.
  • Database - Period for MongoDB database monitoring. Default value is 300 seconds.
  • Collection - Period for MongoDB collection monitoring. Default value is 900 seconds.
  • Top - Period for MongoDB top activity monitoring. Default value is 300 seconds.
  • Shard - Period for MongoDB shard monitoring. Default value is 600 seconds.
  • Replication - Period for MongoDB replication monitoring. Default value is 300 seconds.
  • Profiled Ops Aggregates - Period for MongoDB profiled operation aggregate monitoring. Default value is 900 seconds.
  • Profiled Ops Buffer - Period for MongoDB profiled operation live buffer monitoring. Default value is 900 seconds.
  • Role - Period for MongoDB role monitoring. Default value is 900 seconds.
  • Parameters - Period for MongoDB parameter monitoring. Default value is 3600 seconds.
  • Log - Period for MongoDB log buffer monitoring. Default value is 600 seconds.

Upgrading Foglight for Atlas MongoDB

This section describes about upgrading Atlas agents. Follow the steps below to upgrade the cartridge:

  1. Go to Administration > Cartridges > Cartridge Inventory and click Install Cartridge.
  2. Locate the .car file on your system and install it with auto-enable selected.
  3. Once the Cartridge is installed and enabled, go to Administration > Agents > Agent Managers. Agent Managers with newer agent packages available for upgrade will display “Yes” in the Upgradable | Agents column. Select all Agent Managers to upgrade, then click Upgrade or Deploy Agent Package, and select the AtlasMongoDBAgent package.

If an Agent Manager is not upgradable, verify that its version is compatible with the newer agent version. If it is not compatible, upgrade the Agent Manager first.