slok / grafterm

Metrics dashboards on terminal (a grafana inspired terminal version)

Grafterm

Visualize metrics dashboards on the terminal, like a simplified and minimalist version of Grafana for terminal.

Features

• Multiple widgets (graph, singlestat, gauge).
• Multiple datasources usage.
• User stored datasources.
• Override dashboard datasource ID to different datasource ID configured by the user.
• Custom dashboards based on JSON configuration files.
• Extensible metrics datasource implementation (Prometheus and Graphite included).
• Templating of variables.
• Auto time interval adjustment for queries.
• Auto unit formatting on widgets.
• Fixed and adaptive grid.
• Color customization on widgets.
• Configurable autorefresh.
• Single binary and easy usage/deployment.

Installation

Download the binaries from releases

Running options

Exit with q or Esc

Simple

grafterm -c ./mydashboard.json

Relative time

grafterm -c ./mydashboard.json -d 48h

Refresh interval

grafterm -c ./mydashboard.json -r 2s

Debugging

When grafterm doesn't show anything may be that has errors getting metrics or similar. There is available a --debug flag that will write a log on grafterm.log (this path can be override with --log-path flag)

Read the log

tail -f ./grafterm.log

And run grafterm in debug mode.

grafterm -c ./mydashboard.json  -d 48h -r 2s --debug

Fixed time

Setting a fixed time range to visualize the metrics using duration notation. In this example is start at now-22h and end at now-20h

grafterm -c ./mydashboard.json -s 22h -e 20h

Setting a fixed time range to visualize the metrics using timestamp ISO 8601 notation.

grafterm -c ./mydashboard.json -s 2019-05-12T12:32:11+02:00 -e 2019-05-12T12:35:11+02:00

Replacing dashboard variables

grafterm -c ./mydashboard.json -v env=prod -v job=envoy

Replacing dashboard datasource configuration

Replace dashbaord prometheus datasource with user datasource thanos-prometheus (check Datasources section):

grafterm -c ./mydashboard.json -a "prometheus=thanos-prometheus"

Replace dashboard prometheus datasource with user datasource thanos-prometheus available on /tmp/my-datasources.json user datasource configuration file:

grafterm -c ./mydashboard.json -a "prometheus=thanos-prometheus" -u /tmp/my-datasources.json

Dashboard

Check this section that explains how a dashboard is configured. Also check dashboard examples

Datasources

Datasources are the way grafterm knows how to retrieve the metrics for the dashboard.

check available types and how to configure in this section.

If you want support for a new datasource type, open an issue or send a PR

Overriding dashboard datasources

Dashboard referenced datasources on the queries can be override.

User datasource

Grafterm dashboards can have default datasources but the user can override these datasources using a datasources config file. This file has the same format as the dashboard configuration file but will ignore anything other than the datasources block. Example:

{
  "version": "v1",
  "datasources": {
    "prometheus": {
      "prometheus": { "address": "http://127.0.0.1:9090" }
    },
    "localprom": {
      "prometheus": { "address": "http://127.0.0.1:9091" }
    },
    "thanos": {
      "prometheus": { "address": "http://127.0.0.1:9092" }
    },
    "m3db": {
      "prometheus": { "address": "http://127.0.0.1:9093" }
    },
    "victoriametrics": {
      "prometheus": { "address": "http://127.0.0.1:8428" }
    },
    "wikimedia": {
      "graphite": { "address": "https://graphite.wikimedia.org" }
    }
  }
}

If the dashboard has defined a datasource configuration with the ID my-ds reference, and the user datasources has this same datasource ID, grafterm will use the user defined one when the queries in the dashboard reference this ID.

The user datasources location can be configured with this priority (from highest to lowest):

• If --user-datasources explicit flag is used, it will use this.
• If GRAFTERM_USER_DATASOURCES env var is set, it will use this.
• As a fallback location will check {USER_HOME}/grafterm/datasources.json exists.

Alias

Apart from overriding the dashboard datasources IDs that match with the user datasources, the user can force an alias with the form dashboard-ds-id=user-ds-id.

For example, the dashboard uses a datasource named prometheus-2b, and we want to use our local prometheus configured on the user datasources as localprom, we could use the alias flag like this: -a "prometheus-2b=localprom", now every query the dashboard widgets make to prometheus-2b will be made to localprom.

Kudos

This project would not be possible without the effort of many people and projects but specially Grafana for the inspiration, ideas and the project itself, and Termdash for the rendering of all those fancy graphs on the terminal.

grafterm's Issues

brew install grafterm

Create package for the homebrew (https://brew.sh/), I m working on this feature to create grafterm available on homebrew package manager

Make fails on step 5 (looks like problem with gocenter.io AND problem with mockery)

Just pulled master. On Arch: amd64 Linux. Tried make...

Step 5/15 : RUN go get -u github.com/vektra/mockery/.../
 ---> Running in dcd1965c7357
package github.com/vektra/mockery
        imports github.com/hashicorp/hcl/hcl/printer: cannot find package "github.com/hashicorp/hcl/hcl/printer" in any of:
        /usr/local/go/src/github.com/hashicorp/hcl/hcl/printer (from $GOROOT)
        /go/src/github.com/hashicorp/hcl/hcl/printer (from $GOPATH)
The command '/bin/sh -c go get -u github.com/vektra/mockery/.../' returned a non-zero code: 1
make: *** [Makefile:60: build] Error 1

Ok...

Found this vektra/mockery#364

Modify ./docker/dev/Dockerfile line to ...

# Mock creator
RUN GO111MODULE="on" go get -u github.com/vektra/mockery

Try again ...

Step 5/15 : RUN GO111MODULE="on" go get -u github.com/vektra/mockery
 ---> Running in f240d67d7a70
go get github.com/vektra/mockery: unexpected status (https://gocenter.io/github.com/vektra/mockery/@v/list): 405 Not Allowed

Ok, back to Dockerfile... Change goproxy line to...

ENV GOPROXY=https://proxy.golang.org

Try again...

Step 8/15 : RUN bash -c 'if [ ${ostype} == Linux ]; then addgroup -g $gid app; else addgroup app; fi &&     adduser -D -u $uid -G app app &&     chown app:app -R /go'
 ---> Running in d2ce703cf649
addgroup: gid '0' in use
The command '/bin/sh -c bash -c 'if [ ${ostype} == Linux ]; then addgroup -g $gid app; else addgroup app; fi &&     adduser -D -u $uid -G app app &&     chown app:app -R /go'' returned a non-zero code: 1
make: *** [Makefile:60: build] Error 1

Ok, back to Dockerfile... changed uid and gid variable names...

ARG auid=2000
ARG agid=2000

RUN bash -c 'if [ ${ostype} == Linux ]; then addgroup -g $agid app; else addgroup app; fi && \
    adduser -D -u $auid -G app app && \
    chown app:app -R /go'

Try again...

Step 16/16 : WORKDIR /src
 ---> Running in 4bd2a103b450
Removing intermediate container 4bd2a103b450
 ---> 2aa32cec6d7e
[Warning] One or more build-args [gid uid] were not consumed
Successfully built 2aa32cec6d7e
Successfully tagged grafterm:latest

Success!

Actually building a binary was another slog through the Makefile..

I manually ran VERSION=amd64 ostype=Linux ./hack/scripts/build.sh

❯ ls -l ~/github/grafterm/bin/grafterm-linux-amd64
-rwxr-xr-x 1 ... /home/user/github/grafterm/bin/grafterm-linux-amd64

Cool.

❯ ~/github/grafterm/bin/grafterm-linux-amd64 --help
usage: grafterm [<flags>]

graph metrics on the terminal

Flags:
      --help                     Show context-sensitive help (also try --help-long and --help-man).
      --version                  Show application version.
  -c, --cfg="dashboard.json"     the path to the configuration file
  -r, --refresh-interval=10s     the interval to refresh the dashboard
      --log-path="grafterm.log"  the path where the log output will be written
  -d, --relative-duration=RELATIVE-DURATION
                                 the relative duration from now to load the graph.
  -s, --start=START              the time the dashboard will start in time. Accepts 2 formats, relative time from now based on duration(e.g.: 24h, 15m), or fixed duration in ISO 8601 (e.g.:
                                 2019-05-12T09:35:11+00:00). If set it disables relative duration flag.
  -e, --end=END                  the time the dashboard will end in time. Accepts 2 formats, relative time from now based on duration(e.g.: 24h, 15m), or fixed duration in ISO 8601 (e.g.:
                                 2019-05-12T09:35:11+00:00).
  -v, --var=VAR ...              repeatable flag that will override the variable defined on the dashboard (in 'key=value' form)
  -a, --ds-alias=DS-ALIAS ...    repeatable flag that maps dashboard ID datasources to user defined datasources in the form of 'dashboard=user' (in 'key=value' form)
  -u, --user-datasources="/home/user/grafterm/datasources.json"
                                 path to a configuration file with user defined datasources, these datasources can override the dashboard datasources with the same ID and also can be used to alias
                                 them using datasource alias flags. It fallbacks to GRAFTERM_USER_DATASOURCES env var
      --debug                    enable debug mode, on debug mode it will print logs to the desired output

Hey, it is alive.

❯ ~/github/grafterm/bin/grafterm-linux-amd64 --cfg="/home/$USER/github/grafterm/dashboard-examples/test-grid-adaptive.json"

Yep, that loads the test grid.

Support YAML configuration

YAML can express precisely what JSON can express, but is much easier to write (as it expresses hierarchy through indentation instead of opening/closing brackets).

Therefore, it would be awesome if grafterm could support YAML additionally to JSON 🙂

Allow overriding dashboard datasources with a custom datasource configuration file

When loading a dashboard would be nice to override the datasources of the dashboard using a datasource replace configuration file via flag and/or on a specific path (configured by the user)

Exponential/logarithmic scale for Y axis

Mostly leaving this here as a reminder to myself. It would be nice for some graphs to have a log scale.

Install on centos8

Hi all,
How to install on centos8 !!

Arm release missing

Using GOARM=7 GOARCH=arm for a fourth release in build.sh so it can be used on raspberry pi would be very handy. This is such a neat project to be able to run on my raspberry pi cluster, showing on the little 3.5" screen.

Stretchr/testify v1.4.0 has a security problem (CVE 6.5)

✗ Medium severity vulnerability found in gopkg.in/yaml.v2 (CVE 6.5)
Description: Denial of Service (DoS)
Info: https://snyk.io/vuln/SNYK-GOLANG-GOPKGINYAMLV2-1083943
Introduced through: github.com/stretchr/testify/[email protected]
From: github.com/stretchr/testify/[email protected] > github.com/stretchr/testify/[email protected] > gopkg.in/[email protected]
Fixed in: 2.2.8

Not working on windows

Hi! This looks amazing, but I am having some troubles while trying on windows. I am not sure if I have to install it somehow, but I guess I don't have to. Therefore, I try to run it on the command console, with this result:

I hope it helps!