EventBucket
EventBucket is a global anonymous event hub.
It is global so you can send an event from any application.
For example, every time your nightly build fails, it could send an error event to the EventBucket.
It is anonymous, so all you need to know is the bucket id.
This is why it is so much easier that sending automatic emails - you don't need any authentication to add an event.
Technically speaking, EventBucket is a microservice hosted at
http://eventbucket.romama.com/
How It Works
1. EventBucket stores events in buckets. Every bucket has a globally unique id (GUID).
2. Buckets are anonymous, so anyone can add an event in any bucket (provided you know the bucket id).
3. Bucket contains events. Every event has a level, message and, optionally, details.
4. Every bucket is limited to 100 events. Once full, new events will push out older events.
That's about it.
Monitoring The Bucket
The easiest way to monitor the events in a given bucket is to install the EventBucket Chrome extension.
https://chrome.google.com/webstore/detail/eventbucket/ngkbjogjcpjkaaekpgfcidilofbafllf
Of course, you can write your own tool based on the API/SDK. In fact, it would be very nice if someone created EventBucket client for Android/IOS/Windows platform.
Accessing The Bucket
To access the EventBucket, you have a following choice:
- Over HTTP using EventBucket REST API
- From .NET code using EventBucket SDK
- From .NET using EventBucket NLog target
- From PowerShell using EventBucket PowerShell module
EventBucket REST API
REST API is the most direct way to access the EventBucket. Note that EventBucket API follows HATEOAS principles, so every representation returned by the REST API contain links that you should use to manipulate the resources.
Reserve a bucket
Reserving a bucket is a one time operation. After you reserved a bucket, you can use it for any events you are interested in.
POST
http://eventbucket.romama.com/buckets?invite=92280BD3-94A0-47DF-9BA1-1077AC756633
Request: empty
Response:
{
"id": "5b531043-bddb-4bb9-a54e-5529fc0fd290",
"owner": "",
"created": "2015-05-09T12:27:33.823Z",
"modified": "2015-05-09T12:27:33.823Z",
"links":[
{
"rel": "self",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290"
},
{
"rel": "http://eventbucket.romama.com/rels/addevent";,
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290"
}
]
}
Add an event to the bucket
POST
http://eventbucket.romama.com/bucket/BUCKET_ID
Request:
{
"level": 3,
"message": "The time is running out"
}
Response:
{
"id": "9d203666-e893-4c16-b2cf-496b8ef33aeb",
"bucketid": "5b531043-bddb-4bb9-a54e-5529fc0fd290",
"level": 3,
"message": "The time is running out",
"details": "",
"created": "2015-05-09T12:39:15.243Z",
"links":[
{
"rel": "self",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290/event/9d203666-e893-4c16-b2cf-496b8ef33aeb"
},
{
"rel": "http://eventbucket.romama.com/rels/delete",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290/event/9d203666-e893-4c16-b2cf-496b8ef33aeb"
}
]
}
Event levels are aligned with NLog event levels:
Trace = 0,
Debug = 1,
Info = 2,
Warn = 3,
Error = 4,
Fatal = 5,
Off = 6
Get the bucket
Retrieving the bucket information also retrieves all the events that are currently in that bucket. However, event details are not returned. To get the details of an event, you need to retrieve that event individually.
GET
http://eventbucket.romama.com/bucket/BUCKET_ID
Response:
{
"id": "5b531043-bddb-4bb9-a54e-5529fc0fd290",
"owner": "",
"created": "2015-05-09T12:27:33.823Z",
"modified": "2015-05-09T12:39:15.24Z",
"links":[
{
"rel": "self",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290"
},
{
"rel": "http://eventbucket.romama.com/rels/addevent",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290"
}
],
"events":[
{
"id": "9d203666-e893-4c16-b2cf-496b8ef33aeb",
"bucketid": "5b531043-bddb-4bb9-a54e-5529fc0fd290",
"level": 3,
"message": "The time is running out",
"details": null,
"created": "2015-05-09T12:39:15.243Z",
"links":[
{
"rel": "self",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290/event/9d203666-e893-4c16-b2cf-496b8ef33aeb"
},
{
"rel": "http://eventbucket.romama.com/rels/delete",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290/event/9d203666-e893-4c16-b2cf-496b8ef33aeb"
}
]
}
]
}
Get an event
Retrieving an event returns the complete event data, including details.
GET
http://eventbucket.romama.com/bucket/BUCKET_ID/event/EVENT_ID
Response:
{
"id": "9d203666-e893-4c16-b2cf-496b8ef33aeb",
"bucketid": "5b531043-bddb-4bb9-a54e-5529fc0fd290",
"level": 3,
"message": "The time is running out",
"details": "",
"created": "2015-05-09T12:39:15.243Z",
"links":[
{
"rel": "self",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290/event/9d203666-e893-4c16-b2cf-496b8ef33aeb"
},
{
"rel": "http://eventbucket.romama.com/rels/delete",
"href": "http://eventbucket.romama.com/bucket/5b531043-bddb-4bb9-a54e-5529fc0fd290/event/9d203666-e893-4c16-b2cf-496b8ef33aeb"
}
]
}
Delete an event
DELETE
http://eventbucket.romama.com/bucket/BUCKET_ID/event/EVENT_ID
Response: empty
EventBucket .NET SDK
EventBucket .NET SDK is the simpliest way to access the event bucket from the C# code. However, if you just need to add events, you can use EventBucket NLog target.
To install EventBucket SDK as a Nuget package (
https://www.nuget.org/packages/EventBucket.SDK), run the following command:
Install-Package EventBucket.SDK -Pre
Code sample demonstrating how to access the EventBucket using the SDK:
using Artemkv.EventBucket.SDK;
...
public async Task TestBucketAsync()
{
// Id can be specified as a string
var bucket = await Bucket.GetAsync("5b531043-bddb-4bb9-a54e-5529fc0fd290");
// Or as a GUID
// var bucket = await Bucket.GetAsync(new Guid("5b531043-bddb-4bb9-a54e-5529fc0fd290"));
// Add an event with a message
await bucket.AddEventAsync(Level.Error, "Message from .NET");
// Add an event with a message and details
await bucket.AddEventAsync(Level.Error, "Message from .NET", "Details from .NET");
// Get the latest data of the bucket
bucket = await Bucket.GetAsync(bucket.Id);
// Access events and event properties
var message = bucket.Events[0].Message;
}
EventBucket NLog Target
Configuring the EventBucket NLog target is the simpliest way to add events to the bucket from .NET application without any coding.
To install EventBucket NLog library as a Nuget package (
https://www.nuget.org/packages/EventBucket.NLog), run the following command:
Install-Package EventBucket.NLog -Pre
Sample NLog.config file that uses the EventBucket target:
<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<extensions>
<add assembly="Artemkv.EventBucket.NLog"/>
</extensions>
<targets>
<target xsi:type="EventBucket" name="e" bucketId="5b531043-bddb-4bb9-a54e-5529fc0fd290"
layout="${longdate} ${uppercase:${level}} ${message} ${exception:format=ToString}" />
</targets>
<rules>
<logger name="*" minlevel="Trace" writeTo="e" />
</rules>
</nlog>
EventBucket PowerShell Module
Using PowerShell is the convenient way to add events from the scripts.
Download PowerShell Module
To import the PowerShell module:
Import-Module Artemkv.EventBucket.PowerShell
To get the events in the bucket:
Get-EBEvent -BucketId "5b531043-bddb-4bb9-a54e-5529fc0fd290"
To add the event with the given level and the message to the bucket:
Add-EBEvent -BucketId "5b531043-bddb-4bb9-a54e-5529fc0fd290" -Level Info -Message "Message From Power Shell"
To add the event with the given level, message, and the details to the bucket:
Add-EBEvent -BucketId "5b531043-bddb-4bb9-a54e-5529fc0fd290" -Level Info -Message "Message From Power Shell" -Details "Details From Power Shell"
To filter events by level:
Get-EBEvent -BucketId "5b531043-bddb-4bb9-a54e-5529fc0fd290" | Where-Object {$_.Level -eq "Info"}
To remove the selected events:
Get-EBEvent -BucketId "5b531043-bddb-4bb9-a54e-5529fc0fd290" | Where-Object {$_.Level -eq "Info"} | Remove-EBEvent