The core of current’s data is the log entry, sometimes also called a log message. Because current puts all data into a structured data model, the log entry is itself structured.

Elements

A log entry is composed of 3 elements: timestamp, tags, and attributes.

1. Timestamp

Each entry has a distinct timestamp that has precision down to a single nanosecond. Internally, the values are stored as TAI64N format, which is immune to timezones, leap seconds, daylight saving time.

We consider the timestamp a high value piece of data. Its is a very common way to intepret the order and relationship of entries to eachother.

For this reason, Current stores and retrieves all log entries in proper time order, according to the timestamp itself. In effect, this means that if data was generated an hour ago and only just now reached current.sh’s servers, we store that data in order with other data from an hour ago.

We consider the receive time of the data largely inconsciequental. Buffers, network delays, and a huge number of factors influence this time and it rarely reflects a time that people can make use of.

2. Tags

A tag is a value associated with a key. These identify the who or where of a log entry.

A simple example would be a key environment with a value of production. With log entries carrying that tag, you can easily search for this to see all the production log traffic.

Tags give you an extremely flexible way to organize your log data. You aren’t storing your log data into fixed definition buckets, instead each log entry carries with it information that you can simply query for.

The reason tags are split into a key and a value is to give the tags much more clarity. If they were just a value, then a tag like rails3 would be quite ambigious. But if you see host=rails3 it’s much clearer that rails3 is actually a hostname.

Default Tags

A number of tags are injected automatically based on how current.sh received the data. The most common is syslog where the following tags are added to each log entry:

• @facility: The syslog facility as a string
• @severity: The syslog severity/priority as a string
• @host: The hostname contained in the syslog header

3. Attributes

Attributes are the meat of a log entry. They indicate what actually occured. Current.sh stores all log entries as structured data and attributes are that structure.

Attributes are just a list of keys and values. The meaning of the keys and values is defined entirely by you, the user of the system.

How current takes your data and populates the attributes is covered in Log Formatting.

Attribute Value Types

To give even higher fidelity to the values, current allows for 5 different kinds of value types:

1. String: A simple freeform string. By far the most commonly used
2. Integer: A 64bit integer
3. Float: A 64bit float point number
4. Boolean: true or false
5. Interval: A nanosecond precision time difference. This is included as a core type because, as it’s so common for logs to contain elapse time, we wanted a very high precision value to store those elapse times.

To Tag or to Attribute

The question of where to set a value, in tags or in attributes, is common. There are a few rules to apply to help you decide:

1. Tags are broad strokes. Tags are assigned to large groups of log entries that you want to be able to group together. That’s why things like @environment and @host are common tags. They represent large groups of log entries.
2. If it changes every log entry, it’s an attribute. A simple example would be the userid. While it does group together log entries, it might be different every log entry and the set of entries per userid is likely fairly small in comparison to the number of userids.
3. Tags are the who and where: Which environment was this log entry from? Where was it generated?
4. Attributes are the what. What was the operation? Which user performed it?
5. Tag values are always strings. So if the thing you want to store is not a string, use an attribute.

These are just guidelines, the system is flexible enough to handle most uses of tags and attributes, even if they fall outside these guidelines.

Tags and attributes are separate to give additional categorization power to the users of current.sh. When there is only a single key/value namespace, it can become a big mess trying to figure out how to categorize the entries. Tags are there to give structure to that process.