Grafana is a popular technology that makes it easy to visualize logs and metrics. The Oracle Cloud Infrastructure Logs Data Source for Grafana is used to extend Grafana by adding OCI Logging as a data source. The plugin enables you to visualize log records (service, audit, and custom) and metrics derived from log records stored in the OCI Logging service.
This walkthrough is intended for use by people who would like to deploy Grafana and the OCI Logs Data Source for Grafana on a local Linux server.
Make sure you have access to the Logging Service and that the logs you want to observe and analyze are being collected in your tenancy. See the OCI Logging documentation for information on how to collect or access:
To configure OCI Logging Grafana Data Source, you'll need to get the necessary provider and resource settings. Please note that Migrating from version 2.x.x to 3.x.x will require migrating the existing data source configuration: using version 3.x.x of the plugin with the data source configuration of version 2.x.x is not possible. In case you are migrating from previous version 2.x.x of the OCI Logging Grafana Plugin, you can refer to the Migration Instructions for Grafana OCI Logging Data Source Settings (User Principals and Single Tenancy mode only). If you are configuring the plugin to work in Multitenancy Mode, you will need to repeat the following steps for each of the Tenancies you want to configure with the plugin (up to 5 additional Tenancies are supported).
To get the region for your OCI cloud, follow these steps:
- Log in to the OCI console.
- From the OCI menu, select the Region dropdown in the top right corner of the page.
- The region is listed next to Home.
For details and reference, see: Regions and Availability Domains Please make note of the region as you'll need it later to configure your OCI Logging Grafana Data Source.
To get the tenancy OCID, follow these steps:
- Log in to the OCI console.
- From the OCI menu, click on your profile icon on the top right:
- Click on Tenancy
- The tenancy OCID is listed in the Tenancy Information section.
For details and reference, see: Where to Get the Tenancy's OCID and User's OCID Please make note of the tenancy OCID as you'll need it later to configure your OCI Logging Grafana Data Source.
To get the user OCID, follow these steps:
- Log in to the OCI console.
- From the OCI menu, select Identity > Users.
- Click on the user you want to use with OCI Logging Grafana Data Source.
- The user OCID is listed in the User Details section.
For details and reference, see: Where to Get the Tenancy's OCID and User's OCID. Please make note of the user OCID as you'll need it later to configure your OCI Logging Grafana Data Source.
To get the private key, follow these steps:
- Log in to your OCI tenancy and click on your username in the top right corner.
- Go to Resources and API Keys and click on Add API Key.
- Choose if you want to generate a new API key or use your own:
- Select Generate API Key Pair if you want to generate a new API key. Click then on Download Private Key and Download Public Key to get your newly generated key
- Select Public Key File or Paste Public Key in case you want to paste your public key: select Paste Public Key in the Add API Key dialog and copy and paste the key contents into the field, then click Add.
- Once the key is added take note of the API key fingerprint listed in the Fingerprint column.
For details on how to create and configure keys see How to Generate an API Signing Key and How to Upload the Public Key. Make note of the private key file location and API key fingerprint as you'll need it later to configure your OCI Logging Grafana Data Source.
In the OCI console under Identity > Groups click Create Group and create a new group called grafana. Add the user configured in the OCI CLI to the newly-created group.
Under the Policy tab click Create Policy and create policies allowing the group to read tenancy log objects and content. Add the following policy statements:
allow group grafana to read log-groups in tenancyallow group grafana to read log-content in tenancyallow group grafana to read compartments in tenancyallow group grafana to read audit-events in tenancy
The first two policies can also be limited to specific compartments in your tenancy by adding additional qualifiers to the policy statements.
To install the OCI Logs data source make sure you are running Grafana 8.0 or later. Use the grafana-cli tool to install the Oracle Cloud Infrastructure Logs Data Source for Grafana from the command line:
grafana-cli plugins install oci-logs-datasource
The plugin will be installed into your grafana plugins directory, which by default is located at /var/lib/grafana/plugins. Here is more information on the CLI tool.
Alternatively, you can manually download the .tar file and unpack it into your /grafana/plugins directory. To do so, change to the Grafana plugins directory: cd /usr/local/var/lib/grafana/plugins. Download the OCI Grafana Plugin: wget https://github.com/oracle/oci-grafana-logs/releases/latest/download/plugin.tar. Create a directory and install the plugin: mkdir oci && tar -C oci -xvf plugin.tar and then remove the tarball: rm plugin.tar.
Additional step for Grafana 8. Open the grafana configuration grafana.ini file and add the
allow_loading_unsigned_plugins = "oci-logs-datasource"in the plugins section.
Example
[plugins]
;enable_alpha = false
;app_tls_skip_verify_insecure = false
allow_loading_unsigned_plugins = "oci-logs-datasource"
To start the Grafana server, run: sudo systemctl start grafana-server.
You can use a manual configuration or a programatic configuration. In case you want to use the datasource.yaml based plugin configuration you can refers to this document: Data source configuration using yaml file For manual approach continue to read this document.
The next step is to configure the plugin. Navigate to the Grafana homepage at http://localhost:3000
Log in with the default username admin and the password admin. You will be prompted to change your password. Click Skip or Save to continue.
On the Home Dashboard click the gear icon on the left side of the page and then select Data sources from the Configuration menu.
Click Add data source.
In the search box at the top of the resulting page, enter 'oracle'.
Click the Oracle Cloud Infrastructure Logs box to select it as your data source type.
This Configuration screen will appear:
For Authentication Provider choose local and then choose between single or multitenancy as Tenancy mode. You can then choose between two different modes as Tenancy mode:
- single: to use a single specific Tenancy
- multitenancy: to use multiple tenancies
If you selected single as Tenancy mode then fill in the following credentials:
Profile Name- A user-defined name for this profile. In single mode this is automatically set to DEFAULT and cannot be modified.Region- An OCI region. To get the value, see Getting Region Configuration value.User OCID- OCID of the user calling the API. To get the value, see Getting User OCID Configuration value.*Tenancy OCID- OCID of your tenancy. To get the value, see Getting Tenancy OCID Configuration value.Fingerprint- Fingerprint for the key pair being used. To get the value, see Getting Fingerprint Configuration value.Private Key- The contents of the private key file. To get the value, see Getting Private Key Configuration value.
The configured data source will look like the following:
Click Save & Test to return to the home dashboard.
If you selected multi as Tenancy mode then fill in the following credentials for each Tenancy you want to configure (up to 5 additional tenancies):
Profile Name- A user-defined name for this profile. The first Tenancy is automatically set to DEFAULT and cannot be modified. You need to specify a custom and unique Profile name for each of the additional tenancies.Region- An OCI region. To get the value, see Getting Region Configuration value.User OCID- OCID of the user calling the API. To get the value, see Getting User OCID Configuration value.Tenancy OCID- OCID of your tenancy. To get the value, see Getting Tenancy OCID Configuration value.Fingerprint- Fingerprint for the key pair being used. To get the value, see Getting Fingerprint Configuration value.Private Key- The contents of the private key file. To get the value, see Getting Private Key Configuration value.
By default, if you selected multi as Tenancy mode you can configure one DEFAULT tenancy with an additional one. You may add others tenancy (up to 5 additional tenancies) using the Add another Tenancy checkbox.
The configured data source will look like the following:
Click Save & Test to return to the home dashboard.
After the initial configuration, you can modify the datasource by adding a new tenancy by clicking on the Add another Tenancy checkbox and filling in the additional credentials. You can also disable a configured Tenancy leaving empty the Profile Name as in this screenshot:
On the Oracle Cloud Infrastructure Logs data source configuration page, fill in your Tenancy OCID, Default Region, and Authentication Provider. Your Default region is the same as your home region listed on the Tenancy Details page. For Authentication Provider choose OCI Instance.
Click Save & Test to test the configuration of the Logs data source. Click the Dashboard icon in the left-hand navigation menu to return to the home dashboard.
Check out how to use the newly installed and configured plugin in our Using Grafana with Oracle Cloud Infrastructure Data Source walkthrough.