Fiberplane Templates

Programmatically generate Fiberplane Notebooks for repeatable workflows

Overview

Fiberplane Templates are built with the Jsonnet data templating language.

This crate includes:

• Fiberplane Jsonnet library with functions for creating notebooks (API Docs)
• Rust library for expanding templates into notebooks and for converting existing notebooks into templates

Quickstart

The Fiberplane CLI is the recommended way to interact with Templates (see the docs or run fp help templates).

Structure of a Template

Most Fiberplane Templates export a Jsonnet function that accepts some parameters and creates a notebook using the helper functions provided by the Fiberplane Jsonnet library.

local fp = import 'fiberplane.libsonnet';
local c = fp.cell;
local fmt = fp.format;

// Parameters are named and can have default values
function(incidentName='API Outage')
  fp.notebook
    .new('Incident Response for: ' + incidentName)
    .setTimeRangeRelative(minutes=60)
    .addCells([
      // The library exposes helper functions for creating every cell type
      c.h1('Heading'),
      c.text(
        // There are also helper functions for formatting text
        fmt.bold('Hello World!')
      )
    ])

See the templates repo for more detailed, use-case-specific templates.

Snippets

Snippets are smaller pieces of Jsonnet code that produce reusable arrays of notebook cells, rather than whole notebooks.

local fp = import 'fiberplane.libsonnet';
local c = fp.cell;
local fmt = fp.format;

fp.snippet([
  c.h2('I am a snippet'),
  c.code('Here is some code'),
])

Example Templates

There are example templates for various use cases such as incident response, root cause analysis, etc.

Template API Documentation

See the generated API docs.

Development

VS Code

If you want to edit Jsonnet files in VS Code, you can use the Jsonnet NG extension.

You should add the following to your VS Code settings.json file to edit template files without it showing errors. This includes the Fiberplane Jsonnet library and external variables normally provided by the template expansion functions.

{
  "jsonnet.libPaths": ["path/to/fiberplane/templates/"]
}

Running Tests

To run the tests (including the examples), run:

cargo test --lib --examples

Generating Documentation

The Jsonnet library API documentation is generated from JSDoc comments in fiberplane.libsonnet using jsdoc-to-markdown.

To (re)generate the documentation, you can use this Docker command:

docker run --rm -v $PWD:$PWD node:17 npx -y jsdoc-to-markdown -c $PWD/jsdoc.json $PWD/fiberplane.libsonnet > docs/template_api.md

Alternatively, you can use Node.js directly by using the following command:

npx -y jsdoc-to-markdown -c jsdoc.json fiberplane.libsonnet > docs/template_api.md