Shoreline Grafana Data Source

The Shoreline Grafana data source allows you to create in-depth Grafana dashboards powered by Shoreline's fleetwide resource and metric query capabilities.

Add the data source

1. Login to your Grafana account.

2. In the sidebar hover over Configuration and select Data sources.

3. Enter shoreline in the Filter by name or type field.

4. Select the Shoreline data source.

   

5. Proceed to Configure the data source to finalize setup.

Configure the data source

The Shoreline Grafana data source uses the Shoreline API to make secure requests to your Shoreline cluster.

1. Navigate to the Data Sources / Shoreline Data Source Settings page from the Add the data source steps above.

2. (Optionally) Enter a desired data source name in the Name field.

   

3. Enter your Shoreline API token in the API Key field.

   TIP: See Create a Shoreline API token for help with generating a new key.

   

4. Enter your Shoreline cluster's API URL in the URL field.

   This should be in the format of https://<customer>.<region>.api.shoreline-<cluster>.io.

   

5. Click the Save & test button to complete the configuration.

   You should see a Success message if the configuration was successful.

   

Advanced configuration

Shoreline recommends initially setting only the API Key and URL fields in the data source configuration. In most scenarios, the default HTTP authentication to your Shoreline Cluster works out of the box. However, for more advanced configurations you may need these additional authentication properties.

1. Navigate to the Data Sources / Shoreline Data Source Settings page from the Add the data source steps above.

2. Enable any necessary HTTP auth fields and enter appropriate values.

   The following table describes all the available data source options.

   	Field	Description
   Required	API Key	Your Shoreline API key. See Create a Shoreline API token for help with generating a new key.
   Required	URL	Your Shoreline API URL.
   Optional	Allowed cookies	Specify cookies by name to forward to Shoreline.
   Optional	Timeout	HTTP request timeout, in seconds.
   Optional	Basic auth	Enable for Basic HTTP authentication with a username and password.
   Optional	TLS Client Auth	Enable to use your own TLS certificate. The certificates are encrypted and stored in the Grafana database.
   Optional	Skip TLS Verify	Enable to bypass TLS cert verification.
   Optional	With Credentials	Enable to send credentials such as cookies or auth headers as part of cross-site requests.
   Optional	With CA Cert	Enable to use self-signed TLS certificates.
   Optional	Custom HTTP Headers	Set additional headers.

3. Click the Save & test button to complete the configuration.

Create a Shoreline API token

1. Login to your Shoreline cluster's web UI.

2. Select Configuration from the top dropdown menu.

3. Click on the Access Control card under Administration.

   

4. (Optionally) Click on the Remove all limits button if you do not have Full Administrator access.

5. Click the key button under Actions next to the assigned user.

   TIP: Since the Shoreline Grafana data source user is only issuing resource- and metric-related API requests, we recommend setting Execute actions and Execute Linux cmds to 0 for the Grafana user as an extra security precaution. See Action execution limit and Linux command execution limit in the Shoreline docs for details.

   We also recommend disabling the default Configure role and ensuring the user is not an Administrator.

6. Enter the desired expiration period in the Expires after field.

7. Click the Generate a new API token button.

   

   This token can now be used in the Shoreline Grafana data source configuration.

TIP: See Manage API tokens in the Shoreline docs for more information.

Usage

1. Login to your Grafana account.

2. (Optionally) Create a new Grafana dashboard and add a new panel.

3. Navigate to the Edit panel page of your Grafana dashboard.

4. Select Shoreline Data Source from the Data source dropdown under the Query tab.

   

5. Click on the Select a resource query dropdown and choose a Shoreline Resource query to populate the Resource Query field.

   For example, here we're selecting the hosts Resource query to target all hosts across our entire fleet.

   

   TIP: See the Shoreline Resources docs for full details on using Resource queries.

6. Click on the Select a metric query dropdown and choose a Metric name to populate the Metric Query field.

   For example, here we're selecting the cpu_usage metric to return CPU usage on all hosts within our fleet.

   

7. Click the Refresh button at the top of the Edit Panel page.

   This will force an update and show you appropriate metric data from your Shoreline Resources.

   

You're all set! You can use the built-in Resource and Metric queries to create advanced Grafana dashboards powered by Shoreline metrics:

You can also use additional features provided by Shoreline to improve your Grafana integration experience:

• Create dynamic Grafana dashboards with variable queries
• Create advanced queries with custom OpLang statements
• Add Shoreline event annotations to your Grafana panels

Create variable queries

Shoreline tracks all tags assigned to your Resources, so you can use them in custom Op statements, queries, and much more.

With the Shoreline Grafana data source you can use Shoreline's ability to list built-in Resources to create filterable Resource-based dropdowns in your Grafana dashboards.

1. Navigate to the Edit panel page of your Grafana dashboard.

2. Click on the settings cog button at the top-right.

3. Select Variables from the sidebar.

4. Click the Add variable button.

5. Enter resource_query in the Name field.

6. Enter Resource Query in the Label field.

7. Under Query Options select the Shoreline Data Source from the Data source dropdown.

8. Enter list resources in the Query field.

   In Shoreline's Op language the list resources command retrieves all existing named Resource queries, including built-in queries such as hosts to retrieve all hosts in your fleet.

   For example, the Shoreline CLI output from the list resources command is shown below:

   op> list resources
   TYPE     | NAME                             | DESCRIPTION    | FORMULA                     | PARAMS
   RESOURCE | host                             | All hosts      | resources(type="HOST")      |
   RESOURCE | pod                              | All pods       | resources(type="POD")       |
   RESOURCE | container                        | All containers | resources(type="CONTAINER") |
   RESOURCE | hosts                            | All hosts      | resources(type="HOST")      |
   RESOURCE | pods                             | All pods       | resources(type="POD")       |
   RESOURCE | containers                       | All containers | resources(type="CONTAINER") |
   

   TIP: Check out the Named Resource documentation for more information on custom Resource queries.

9. Enter /[^(pod|container)s]/ in the Regex field.

   This restricts the resulting Resources to host-level objects.

   

10. Click the Update button to create your variable.

Now we'll create a second variable so you can select specific hosts using the results of the query above.

1. Click the New button on the Variables page to create a new variable.

2. Enter hosts in the Name field.

3. Enter Hosts in the Label field.

4. Under Query Options select the Shoreline Data Source from the Data source dropdown.

5. Enter ${resource_query} in the Query field.

   This is Grafana's syntax to interpolate a variable within the expression. In this case, we're using the results of the query to create a dependant variable.

6. (Optionally) Tick the Multi-value checkbox to allow you to select multiple values.

7. (Optionally) Tick the Include All option checkbox to allow you to simultaneously select all values.

   

8. Click the Update button.

Your Grafana dashboard now has two variable dropdowns for Resource Query and Hosts, which allow you to select the resource type (hosts) and then the specific host Resources.

The final step is to pass this new variable to Shoreline with a custom OpLang statement.

Using custom OpLang statements

Shoreline's powerful Op language helps operators quickly execute commands and retrieve data across their entire fleet with a single line of code.

The Shoreline Grafana data source allows you to create custom Shoreline Resource and Metric queries to retrieve exactly the data you want from a precise collection of resources.

In this case, we'll use a custom OpLang statement to accurately retrieve the host Resources assigned to the hosts variable in the Create variable queries section.

1. Navigate to the Edit panel page of your Grafana dashboard.
2. Tick the Custom checkbox Under a Shoreline Data Source query accordion panel.
3. Enter any valid Op Metric query in the OpLang Statement field.
4. Click the Refresh button at the top of the Edit Panel page.

You'll now see the desired metric data from the targeted Resources.

For example, here we're using the hosts | name=${hosts:json} | cloud_provider="aws" | cpu_usage Op statement to retrieve CPU usage data across all our hosts that are hosted on AWS, rather than Azure or GCP. We're comparing the name tag of all the host Resources in the entire fleet and selecting only those that match the current resources assigned to the Grafana hosts variable from the previous steps.

You're all set! You can now select any number of hosts from the Hosts variable dropdown to dynamically adjust which Resources you're monitoring.

TIP: Check out the Shoreline Resources and Metrics docs for more information on custom Op statements.

Add Shoreline event annotations

Shoreline's observability and auto-remediation capabilities are built around a collection of Shoreline objects such as Alarms, Actions, Bots, Resources, and more. Each of these objects generates annotations called Events.

The Shoreline Grafana integration allows you to view Shoreline Event annotations directly within your Grafana dashboards.

1. Navigate to the Edit panel page of your Grafana dashboard.

2. Click on the settings cog button at the top-right.

3. Select Annotations from the sidebar.

4. Click the Add annotation query button.

5. Enter a desired name in the Name field.

6. Select Shoreline Data Source in the Data source dropdown.

7. Enter a valid Event query Op statement in the Shoreline annotation query field.

   For example, here we're retrieving all Alarm Events with events | type="alarm", which includes when Alarms are triggered and resolved.

   

8. Click the Save dashboard button in the sidebar to finalize your changes.

Your dashboard panel now shows toggleable annotations for your Shoreline Alarms that triggered or resolved on the targeted Resources.