Findings API

Motivation

Playbooks should use the Findings API to display output. They should not send output directly to Slack or other destinations.

By using the Findings API, your playbook will support Slack, MSTeams, and other sinks.

Basic Usage

Playbooks can call event.add_enrichment to add to the playbook’s output. For example:

@action
def test_playbook(event: ExecutionBaseEvent):
    event.add_enrichment(
        [
            MarkdownBlock(
                "This is a *markdown* message. Here are some movie characters:"
            ),
            TableBlock(
                [["Han Solo", "Star Wars"], ["Paul Atreides", "Dune"]],
                ["name", "movie"],
            ),
        ]
    )

When playbooks finish running, their output is sent to the configured sinks. Here is output for the above example:

Slack

Core Concepts

The Findings API has four important concepts:

Finding

An event, like a Prometheus alert or a deployment update.

Enrichment

Details about a Finding, like the labels for a Prometheus alert or a deployment’s YAML before and after the update.

Block

A visual element, like a paragraph, an image, or a table.

Sink

A destination Findings are sent to, like Slack, MSTeams, Kafka topics

Here is an example showing the above concepts:

Advanced Usage

It is possible to customize a findings name, override the default finding for events, and more.

But we haven’t documented it yet. Please consult the source code.

class Finding(title, aggregation_key, severity=FindingSeverity.INFO, source=FindingSource.NONE, description=None, subject=<robusta.core.reporting.base.FindingSubject object>, finding_type=FindingType.ISSUE, failure=True)

A Finding represents an event that should be sent to sinks.

add_enrichment(enrichment_blocks, annotations=None)

Block Types

Every Block represents a different type of visual data. Here are the possible Blocks:

MarkdownBlock(text[, dedent])	A Block of Markdown
FileBlock(filename, contents)	A file of any type.
DividerBlock(**data)	A visual separator between other blocks
HeaderBlock(text)	Text formatted as a header
ListBlock(items)	A list of items, nicely formatted
TableBlock(rows[, headers, column_renderers])	Table display of a list of lists.
KubernetesFieldsBlock(k8s_obj, fields[, ...])	A nicely formatted Kubernetes objects, with a subset of the fields shown
KubernetesDiffBlock(interesting_diffs, old, new)	A diff between two versions of a Kubernetes object
JsonBlock(json_str)	Json data
CallbackBlock(choices)	A set of buttons that allows callbacks from the sink - for example, a button in Slack that will trigger another action when clicked

Note

Not all block types are supported by all sinks. If an unsupported block arrives at a sink, it will be ignored

Reference

class MarkdownBlock(text, dedent=False)

A Block of Markdown

Parameters

• text (str) – one or more paragraphs of Markdown markup

• dedent (bool) – if True, remove common indentation so that you can use multi-line docstrings.

A simple example:

MarkdownBlock("Hi, *I'm bold* and _I'm italic_")

Things can get hairy when using writing content across multiple lines:

MarkdownBlock(
    "# This is a header \n\n"
    "And this is a paragraph. "
    "Same paragraph. A new string on each line prevents Python from adding newlines."
),

For convenience, use strip_whitespace=True and multiline strings:

MarkdownBlock("""
    Due to strip_whitespace=True this is all one
    paragraph despite indentation and newlines.
    """, strip_whitespace=True)

class FileBlock(filename, contents)

A file of any type. Used for images, log files, binary files, and more.

Parameters

• filename (str) – the file’s name

• contents (bytes) – the file’s contents

Examples:

FileBlock("test.txt", "this is the file's contents")

class DividerBlock(**data)

A visual separator between other blocks

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

class HeaderBlock(text)

Text formatted as a header

Parameters

text (str) – the header

class ListBlock(items)

A list of items, nicely formatted

Parameters

items (List[str]) – a list of strings

class TableBlock(rows, headers=(), column_renderers={})

Table display of a list of lists.

Parameters

• rows (List[List]) – a list of rows. each row is a list of columns

• headers (Sequence[str]) – names of each column

class KubernetesFieldsBlock(k8s_obj, fields, explanations={})

A nicely formatted Kubernetes objects, with a subset of the fields shown

Parameters

• k8s_obj (HikaruDocumentBase) – a kubernetes object

• fields (List[str]) – a list of fields to display. for example [“metadata.name”, “metadata.namespace”]

• explanations (Dict[str, str]) – an explanation for each field. for example {“metdata.name”: “the pods name”}

class KubernetesDiffBlock(interesting_diffs, old, new)

A diff between two versions of a Kubernetes object

Parameters

• interesting_diffs (List[DiffDetail]) – parts of the diff to emphasize - some sinks will only show these to save space

• old (Optional[HikaruDocumentBase]) – the old version of the object

• new (Optional[HikaruDocumentBase]) – the new version of the object

class JsonBlock(json_str)

Json data

Parameters

json_str (str) – json as a string

class CallbackBlock(choices)

A set of buttons that allows callbacks from the sink - for example, a button in Slack that will trigger another action when clicked

Parameters

choices (Dict[str, CallbackChoice]) – a dict mapping between each the text on each button to the action it triggers