Copying signals and dashboards using seqcli templates

Templates make it easy to copy entities like signals and dashboards from one Seq server to one or more others:

• Between isolated dev, test, and production environments,
• Through blog posts and support documentation, and
• Between developers on a team.

(We're really excited about the last one, because keeping a stash of relevant signals and dashboards will be a great way to get new developers up and running with a useful local Seq instance when joining a project.)

This post covers the fundamentals, but templates are really self-explanatory, and you should be able to achieve just about anything you need to using the information here, in conjunction with the seqcli help template export and seqcli help template import command-line help.

An example signal and dashboard

Our example Seq instance has a selection of signals that identify log events raised when the Seq Cafe roastery receives orders and ships them.

We also have a nice order status dashboard that shows orders flowing through the roastery:

We'll move both the signals and related dashboard to a fresh Seq instance using templates.

The important thing that templates account for is the relationship between the two: the dashboard, when its imported into another Seq instance, needs a reference to the imported copies of the signals.

Exporting the template

The first step when exporting entities from a Seq server is to make a directory for the template files:

mkdir cafe
cd cafe

Then, pointing seqcli at the source server (and using an API key, if required), run:

seqcli template export -s https://source.example.com

The default output location is ., so if you run ls you should see a list of files along these lines:

dashboard-Orders.template
signal-Order Abandoned.template
signal-Order Created.template
signal-Order Placed.template
signal-Order Shipped.template

I've deleted everything except for the dashboard and signals we intend to export.

If the entities you're expecting aren't there, you may need to share them, or identify them explicitly on the template export command-line using -i <id>. By default, seqcli will only export shared entities.

Peeking inside the template files

The template files are plain text. Here are the first dozen lines or so lines of dashboard-Orders.template:

{
  "$entity": "dashboard",
  "OwnerId": null,
  "Title": "Orders",
  "IsProtected": false,
  "SignalExpression": null,
  "Charts": [
    {
      "Title": "Order Lifecycle",
      "SignalExpression": null,
      "Queries": [
        {
          "Measurements": [
            {
              "Value": "count(@EventType = 0x8CC54029)",
              "Label": "shipped"
            },

If you've spent time using Seq's HTTP API, the entity structure here will be familiar.

Template files are JSON with placeholders. A little farther down in the dashboard template, where the dashboard makes reference to one of the associated signals, you'll see a placeholder:

    {
      "Title": "Created",
      "SignalExpression": {
        "SignalId": ref("signal-Order Created.template"),
        "Kind": "Signal"
      },
      "Queries": [

The function-call-like ref("signal-Order Created.template") looks up the id of the signal that was imported from the signal-Order Created.template file on the target server.

Importing again

Importing the template into the target server is as easy as:

seqcli template import -s https://dest.example.com --state ./dest.state

You'll notice that the import command accepts the path of a state file: this file tracks the mapping between templates and the entity ids assigned to them on the target Seq server. If the same state file is used in later imports, entities that already exist will be updated instead of duplicated.

Here's our target server, with the dashboard and signals imported 😎.

Getting seqcli

The Seq installer for Windows includes a copy of seqcli, so you'll find it's already on the PATH if you have Seq installed on that OS.

For macOS and Linux, binaries can be downloaded from GitHub, or, you can docker run the datalust/seqcli container.

Have fun!