Annotations

The annotations API allows you to read and write events into TraceView, to help understand the correlation between system events and performance trends. Common events include:

  • Code releases
  • Server restarts
  • Network upgrades
  • Configuration changes

Command Line

On machines with the TraceView agent installed, you can just use the tlog script to create annotations.

$ tlog -m "Deployed revision ac341bf"

You can also associate your message with a particular app, or override the hostname.

$ tlog -m "Deployed revision ac341bf" \
    -a "Default" \
    -H "traceview-app-37"

REST

You can also post directly to our URL. The only required parameters are your client key and the message.

POST /api-v2/log_message

Value Description
message Message to log
appname Name of the app to associated this message with (optional).
hostname Name of the host to assign to the app (optional)
username User who logged this message (optional)
time Time this message occurred, in seconds since the epoch (optional)

Annotations can be viewed in the context of server-side data in your application.

Example

from urllib import urlencode
from urllib2 import urlopen, URLError
import time

logkvs = {
    'key': key,
    'message': msg,
    'appname': appname,
    'time': time.time()
}

try:
    res = urlopen(TLOG_API_URL, urlencode(logkvs))
except URLError as e:
    print "Error sending log message: %s" % e

Annotations

GET /api-v2/annotations

Returns a list of annotations on all apps. The default time window is 1 week; alternate time windows can be specified by UTC timestamp in milliseconds via optional parameters time_start and time_end (eg. GET /api-v2/annotations?time_start=123456789000&time_end=987654321000)

Sample

{
    "data":[
        {
            "id": 36583,
            "message": "deployed version 1.1",
            "username": "Appneta",
            "hostname": "host1.example.com",
            "app": "Default",
            "timestamp": 1378495042
        },
        {
            "id": 10378,
            "message": "deployed version 1.2",
            "username": "Appneta",
            "hostname": "host2.example.com",
            "app": "Production",
            "timestamp": 1381028937
        }
    ],
    "response":"ok"
}

Annotations by App

GET /api-v2/app/<appname>/annotations

Returns a list of annotations on the specified app. The default time window is 1 week; alternate time windows can be specified by UTC timestamp in milliseconds via optional parameters time_start and time_end (eg. GET /api-v2/app/Default/annotations?time_start=123456789000&time_end=987654321000)

Sample

{
    "data":[
        {
            "id": 58338,
            "message": "deployed version 2.8",
            "username": "Appneta",
            "hostname": "host1.example.com",
            "app": "Default",
            "timestamp": 1378495042
        },
        {
            "id": 93802,
            "message": "server down",
            "username": "Traceview",
            "hostname": "host2.example.com",
            "app": "Default",
            "timestamp": 1409867450
        }
    ],
    "response":"ok"
}

Table Of Contents

Related Topics