1 Sending On-demand Notification

This tour shows you how to send a notification to a receiver. You need to pick to which receiver you want send the notification to. If the receiver is not added in Siren yet, you could add one using siren receiver create. See receiver guide to explore more on how to work with siren receiver command.

Receiver in Siren is implemented as a plugin. Read here to understand the concept about Plugin. There are several types of receiver supported in Siren. In this tour we want to send a notification to a file receiver type. More detail about file receiver type can be found here.

We welcome all contributions to add new type of receiver plugins. See Extend section to explore how to add a new type of receiver plugin to Siren

1.1 Register a Receiver

With file receiver type, all published notifications will be written to a file. Let's create a file receiver using Siren CLI.

Prepare receiver detail.

receiver_1.yaml

name: file-sink-1
type: file
labels:
    key1: value1
    key2: value2
configurations:
    url: ./out-file-sink1.json

Register the receiver with this command.

CLI

$ siren receiver create --file receiver_1.yaml

Once done, you will get a message.

Receiver created with id: 1 ✓

HTTP

$ curl --request POST
  --url http://localhost:8080/v1beta1/receivers
  --header 'content-type: application/json'
  --data-raw '{
    "name": "file-sink-1",
    "type": "file",
    "labels": {
        "key1": "value1",
        "key2": "value2"
    },
    "configurations": {
        "url": "./out-file-sink1.json"
    }
}'

You could verify the registered receiver by getting all receivers or get the new registered receiver by passing the ID. This command is to get all receivers in Siren.

CLI

$ siren receiver list

HTTP

$ curl --request GET
  --url http://localhost:8080/v1beta1/receivers
  

Or view a specific receiver with its ID with this command. For example the ID is 1.

CLI

$ siren receiver view 1

HTTP

$ curl --request GET
  --url http://localhost:8080/v1beta1/receivers/1
  

1.2 Sending Notification to a Receiver

In previous part, we have already registered a receiver in Siren and got back the receiver ID. Now, we will send a notification to that receiver. If you are curious about how notification in Siren works, you can read the concepts here.

To send a notification, we need to prepare the message payload as yaml to be sent by Siren CLI. The message is expected to be in a key-value format and placed under payload.data.

Prepare a message to send to receiver 1.

message_file_1.yaml

payload:
    data:
        text: this is notification to file 1
        a_field: a_value
        another_field: another_value

Then we can run receiver send command and target the receiver id 1 with flag --id.

CLI

$ siren receiver send --id 1 --file message_file_1.yaml

HTTP

$ curl --request POST
  --url http://localhost:8080/v1beta1/receivers/1/send
  --header 'content-type: application/json'
  --data-raw '{
    "payload": {
        "data": {
            "text": "this is notification to file 1",
            "a_field": "a_value",
            "another_field": "another_value"
        }
    }
}'

If succeed, one new file should have been created: out-file-sink1.json and the file will have this text.

// out-file-sink1.json
{"a_field":"a_value","another_field":"another_value","routing_method":"receiver","text":"this is notification to file 1"}

What Next?

Well done, you just completed a tour to send an on-demand notification. The next tour will be around how to create alerting rules and subscribe a notification if an alert is triggered.

Apart from the tour, we recommend completing the guides. You could also check out the remainder of the documentation in the reference and concepts sections for your specific areas of interest. We've aimed to provide as much documentation as we can for the various components of Siren to give you a full understanding of Siren's surface area. If you are interested to contribute, check out the contribution page.