Creating Findings¶

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, creation_date=None, fingerprint=None, starts_at=None, ends_at=None, add_silence_url=False, silence_labels=None)[source]¶

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

property attribute_map : dict[str, str | dict[str, str]]¶

Return type:¶

Dict[str, Union[str, Dict[str, str]]]

get_investigate_uri(account_id, cluster_name=None)[source]¶

add_enrichment(enrichment_blocks, annotations=None, suppress_warning=False, enrichment_type=None, title=None)[source]¶

add_video_link(video_link, suppress_warning=False)[source]¶

get_prometheus_silence_url(account_id, cluster_name)[source]¶

Return type:¶

str

Block Types¶

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

Reference¶

class MarkdownBlock(text, dedent=False)[source]¶

A Block of Markdown

Parameters:¶

text¶

one or more paragraphs of Markdown markup

dedent=False¶

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, **kwargs)[source]¶

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

Parameters:¶

filename¶

the file's name

contents¶

the file's contents

Examples:

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

class DividerBlock(**data)[source]¶

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)[source]¶

Text formatted as a header

Parameters:¶

text¶

the header

class ListBlock(items)[source]¶

A list of items, nicely formatted

Parameters:¶

items¶

a list of strings

class TableBlock(rows, headers=(), column_renderers={}, table_name='', column_width=None, metadata={}, table_format=None, **kwargs)[source]¶

Table display of a list of lists.

Note: Wider tables appears as a file attachment on Slack, because they aren't rendered properly inline

Variables:¶

column_width=None¶

Hint to sink for the portion of size each column should use. Not supported by all sinks. example: [1, 1, 1, 2] use twice the size for last column.

Parameters:¶

rows¶

a list of rows. each row is a list of columns

headers=()¶

names of each column

class KubernetesFieldsBlock(k8s_obj, fields, explanations={})[source]¶

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

Parameters:¶

k8s_obj¶

a kubernetes object

fields¶

a list of fields to display. for example ["metadata.name", "metadata.namespace"]

explanations={}¶

an explanation for each field. for example {"metadata.name": "the pods name"}

class KubernetesDiffBlock(interesting_diffs, old, new, name, kind, namespace=None)[source]¶

A diff between two versions of a Kubernetes object

Parameters:¶

interesting_diffs¶

parts of the diff to emphasize - some sinks will only show these to save space

old¶

the old version of the object

new¶

the new version of the object

class JsonBlock(json_str)[source]¶

Json data

Parameters:¶

json_str¶

json as a string

class CallbackBlock(choices)[source]¶

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¶

a dict mapping between each the text on each button to the action it triggers