Plugins 〉Shoreline Data Source
Shoreline Data Source
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
Login to your Grafana account.
In the sidebar hover over Configuration and select Data sources.
Enter
shoreline
in the Filter by name or type field.Select the Shoreline data source.
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.
Navigate to the Data Sources / Shoreline Data Source Settings page from the Add the data source steps above.
(Optionally) Enter a desired data source name in the Name field.
Enter your Shoreline API token in the API Key field.
TIP: See Create a Shoreline API token for help with generating a new key.
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
.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.
Navigate to the Data Sources / Shoreline Data Source Settings page from the Add the data source steps above.
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. Click the Save & test button to complete the configuration.
Create a Shoreline API token
Login to your Shoreline cluster's web UI.
Select Configuration from the top dropdown menu.
Click on the Access Control card under Administration.
(Optionally) Click on the Remove all limits button if you do not have Full Administrator access.
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
andExecute Linux cmds
to0
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.
Enter the desired expiration period in the Expires after field.
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
Login to your Grafana account.
(Optionally) Create a new Grafana dashboard and add a new panel.
Navigate to the Edit panel page of your Grafana dashboard.
Select
Shoreline Data Source
from the Data source dropdown under the Query tab.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.
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.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.
Navigate to the Edit panel page of your Grafana dashboard.
Click on the settings cog button at the top-right.
Select Variables from the sidebar.
Click the Add variable button.
Enter
resource_query
in the Name field.Enter
Resource Query
in the Label field.Under Query Options select the
Shoreline Data Source
from the Data source dropdown.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.
Enter
/[^(pod|container)s]/
in the Regex field.This restricts the resulting Resources to host-level objects.
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.
Click the New button on the Variables page to create a new variable.
Enter
hosts
in the Name field.Enter
Hosts
in the Label field.Under Query Options select the
Shoreline Data Source
from the Data source dropdown.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.
(Optionally) Tick the Multi-value checkbox to allow you to select multiple values.
(Optionally) Tick the Include All option checkbox to allow you to simultaneously select all values.
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.
- Navigate to the Edit panel page of your Grafana dashboard.
- Tick the Custom checkbox Under a Shoreline Data Source query accordion panel.
- Enter any valid Op Metric query in the OpLang Statement field.
- 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.
Navigate to the Edit panel page of your Grafana dashboard.
Click on the settings cog button at the top-right.
Select Annotations from the sidebar.
Click the Add annotation query button.
Enter a desired name in the Name field.
Select
Shoreline Data Source
in the Data source dropdown.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.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.
Grafana Cloud Pro
- $25 / user / month and includes a free trial for new users
- Available with a Grafana Cloud Pro plan
- Access to 1 Enterprise plugin
- Fully managed service (not available to self-manage)
Grafana Cloud Advanced / Grafana Enterprise
- Available with a Grafana Cloud Advanced plan or Grafana Enterprise license
- Access to all Enterprise plugins
- Run fully managed or self-manage on your own infrastructure
Installing Shoreline Data Source on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install Shoreline Data Source from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section.
Next, click the Add data source button in the upper right. The data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Changelog
1.1.0
- Add support for
metric_metadata_query
as variable query - Add support for custom HTTP settings when configuring data source
- Add documentation and examples in plugin README
- Fix bug where checkbox setting for custom query doesn't always get saved
1.0.0
Initial release.