grafctl

grafctl is a command line tool for interacting with Grafana. Its primarily intended to be used with foyle.io and Runme.dev.

grafctl is designed to work with Grafana's Explore feature. grafctl makes it easy to define your visualizations inside your Runme.dev notebook and then generate links to the visualization.

Quickstart

Install

Download the latest release from the releases page

Parse An Existing Explore Link

The easiest way to understand the query syntax for a dashboard is by opening up an existing dashboard in the explore panel. You can then get the link for that Explore query by clicking the share button and selecting "Copy Absolute URL."

Once you have the URL you can parse it using grafctl

grafctl links parse --url=${URL}

This will output a GrafanaLink resource like the one below.

apiVersion: grafctl.foyle.io/v1alpha1
kind: GrafanaLink
metadata:
  labels: {}
baseURL: https://applied-grafana-abcd.grafana.azure.com
panes:
  oy8:
    datasource: effb3d
    queries:
      - datasource:
          type: prometheus
          uid: effb3d
        expr: process_resident_memory_bytes{instance=~"(10\\.0\\.188\\.174:9153)"}
        interval: ""
        legendFormat: '{{instance}}'
        range: true
        refId: A
    range:
      from: "now-5m"
      to: "now"

The fields in the query resource will vary depending on your datasource. In the example above we are querying prometheus for process_resident_memory_bytes.

Generate an Explore Link

You can generate a link for an Explore view by specifying a GrafanaLink resource that contains the query parameters for your query e.g

cat <<'EOF' > /tmp/query.yaml
apiVersion: grafctl.foyle.io/v1alpha1
kind: GrafanaLink
metadata:
  labels: {}
baseURL: https://applied-grafana-abcd.grafana.azure.com
panes:
  oy8:
    datasource: effb3d
    queries:
      - datasource:
          type: prometheus
          uid: effb3d
        expr: process_resident_memory_bytes{instance=~"(10\\.0\\.188\\.174:9153)"}
        interval: ""
        legendFormat: '{{instance}}'
        range: true
        refId: A
    range:
      from: "now-5m"
      to: "now"
EOF
grafctl links build -p=/tmp/query.yaml --open

Important Note that EOF is enclosed in single quotes. This prevents escaping and shell interpolation. Without this shell escaping and interpolation can prevent the query from being encoded correctly.

Generating Links From Patches

GrafanaLink resources can be quite verbose with only one or two fields changing. For the prometheus query in the previous section, you likely only need to change two fields for each query

expr which contains your actual prometheus query
range which is the time range for your query

grafctl lets you define a links by applying a JSON merge patch to a base resource.

Create Base Resources

Define one or more base resources in your ~/.grafctl directory. These will be GrafanaLink resources that define a template for each dashboard you want to generate links for.

In Grafana, open the dashboard that you would like to generate links for
Configure the dashboard it serves as an example of the views you want to generate
In the UI click the share button to get a URL for the graph;
- Do not use the short link
Use the links parse command to generate a base resource and save it to a file in your ~/.grafctl directory
```
grafctl links parse --url=${URL} -o ~/.grafctl/${NAME}.yaml
```
- By default the GrafanaLink resource is given the name ${NAME} but you can override it by specifying the --name=${CUSTOMNAME} flag

Generate Links

Now you can generate links by defining a patch file that specifies the query and time range for the link.

Here's an example

cat <<'EOF' >/tmp/patch.yaml
apiVersion: grafctl.foyle.io/v1alpha1
kind: PanePatch
template: somequery
query:
    builderOptions:
        logQuery: "service:app"
range: 
    from: "now-1h"
    to: "now"
EOF
grafctl links build -p /tmp/patch.yaml

This will print out a hyperlink to Grafana.

template is the name of the GrafanaLink to use as the base resource
- The name is stored in the yaml file
```
apiVersion: grafctl.foyle.io/v1alpha1
kind: GrafanaLink
metadata:
  name: sql
```
query This is the patch to be applied to the query
- The fields you need to set will be specific to your dashboard
range specifies the time range for the query using grafana's syntax for relative time ranges. By default relative time ranges are converted to absolute time ranges before constructing the URL in order to generate a stable URL. If you want relative times in the url add the field fixTime: false to the patch.

grafctl will apply the patch to the first query in the template if your template contains more than one query.

# README