Seismo

Simple tool to track and analyze application events. Ideal for startups.

Description

It should be easy to start collecting application events in order to understand what's going on inside, users activity and performance issues. We solve that by logging application events to some storage and when build reports based on this data.

There are few solutions that allows to do that. But you might decided to track on your own, fully controlling the flow and also make a solution cheap. Thats there Seismo will help.

Simple architecture

It's build upon open source technology and it's open-source by itself. Simple deploy and infrastructure around will give you able to not dive upon in details, but simply use it.

MongoDB is used as server database, there events are stored. Express.js application exposes REST API, there you post events and build reports on.

Docker friendly

Server is easy deployable on any Node.js-friendly system. But to make deployment event more simple, we provide Docker image and all you need to do after just run we bash commands to start.

Clients

The clients are also part of project. Just for now we have Express.js/Node.js client, but will support client apps, Ruby, Python and different combinations of languages and frameworks. Since the clients are simple HTTP applications, it's really easy to extend the support.

Installation

There are few ways you can install seismo locally. It's availabled on npm, github and docker index.

NPM installation

Seismo server is available on npm.

$ npm install seismo

Configuration

In order to run it, you have to provide configuration. Configuration is object, which includes several properties:

var config = {
	connection: 'CONNECTION_STRING',		// [string] connection string to mongo
	authKey: 'SHARED_SECRET',				// [string] used to sign server tokens,
	tokenTtl: 60,							// [int] token time-to-leave in minutes, default is 60 (hour)
	users: {
		'user': 'BCRYPTED_PASSWORD_HASH'	// [string:string] pairs of user name and bcrypted passwords (IMPORTANT, bcrypt with 12 rounds must be used)
		/* as many as needed */
	}
};

Start seismo server,

var seismo = require('seismo');
seismo.start(config, function (err) {
	console.log('seismo server started');
});

GitHub installation

It also possible just clone repo, modify the configuration and start the server.

$ git clone https://github.com/likeastore/seismo.git
$ cd seismo

Apply changes into /config and start server.

$ code src/server.js

Docker installation

TDB.

REST API

Here is the description of Seismo REST interface.

Authentication

Clients have to authenticated in order to access API. We used simple authentication flow, based on GitHub. Authenticated users are generating Personal Tokens.

There is a configuration file, there you specify GitHub accounts that are permitted to access API.

// config.js

var config = {
	auth: {
		users: [
			'alexanderbeletsky',
			'voronianski'
		]
	}
};

API endpoint,

HTTP POST http://analytics.host/auth

var payload = {
	token: 'GITHUB_PERSONAL_TOKEN'
};

If personal token belongs to user specified in configuration file, the permissions are granted. Access token is returned to client. Access token is used as either X-Access-Token request header, or ?access_token= query parameter or token cookie value.

Application ID

Application ID is association between events and application that generates it. One server could handle as many as needed.

Posting Events

HTTP POST http://analytics.host/api/events/:app-id

{
	event: 'event',
	data: {}
}

With event id and event name,

HTTP POST http://analytics.host/api/events/:app-id

{
	event: {id: 'app-start', event: 'application started'},
	data: {}
}

With additional event payload,

HTTP POST http://analytics.host/api/events/:app-id

{
	event: 'application started',
	data: {environment: 'production'}
}

Querying Events

All events generated by app,

HTTP GET http://analytics.host/api/events/:app-id

By event name,

HTTP GET http://analytics.host/api/events/:app-id?event=search%20executed

By event id,

HTTP GET http://analytics.host/api/events/:app-id?id=app-start

Today events,

HTTP GET http://analytics.host/api/events/:app-id?date=today

Or by date,

HTTP GET http://analytics.host/api/events/:app-id?date=2014-09-26

Or combination,

HTTP GET http://analytics.host/api/events/:app-id?event=search%20executed&date=today

Building Reports

Events for one hour for given date,

HTTP GET http://analytics.host/api/reports/hour/:app-id?hour=6&date=2013-09-29

By given date,

HTTP GET http://analytics.host/api/reports/day/:app-id?date=2013-09-29

By given week,

HTTP GET http://analytics.host/api/reports/week/:app-id?week=2013-09-29

By given month,

HTTP GET http://analytics.host/api/reports/month/:app-id?month=2013-09-29

By any period,

HTTP GET http://analytics.host/api/reports/period/:app-id?from=2013-09-10&to=2013-09-13

License

MIT

alexbeletsky/seismo