What is it ?

The Honeycomb purpose is to store and serve your collected data.

Deploy your own honeycomb

The Honeycomb server can be deployed anywhere, given it is linked to your dashboard and provided a mongodb database.

Download a Honeycomb

The honeycomb is a scala Play! server available as a docker image on the docker hub.

Configuration

The Honeycomb configuration can be changed thanks to environment variables:

  • Mandatory configuration:
  • Customize the Honeycomb behaviour:
    • HONEYCOMB_MAX_DISK_BUFFER: Maximum size for the uploaded media files (default: 100M).
    • HONEYCOMB_MAX_MEMORY_BUFFER: Maximum size for the uploaded json files (default: 500K).
    • HONEYCOMB_RESPONSE_LIMIT: Maximum number of element contained in a data page (default: 10, unlimited if negative).
    • HONEYCOMB_DATA_QUOTA: Default quota set to each new user by default (default: 500M, unlimited if 0).
  • Configure MongoDB:
    • MONGODB_PORT_27017_TCP_ADDR: Mongodb server host. (Automatically filled if using a linked docker container).
    • MONGODB_PORT_27017_TCP_PORT: Mongodb server port. (Automatically filled if using a linked docker container).
    • HONEYCOMB_MONGODB_USERNAME: Mongodb user to be used by the Honeycomb, not used if left empty.
    • HONEYCOMB_MONGODB_PASSWORD: Password of the previous user, not used if left empty.
    • HONEYCOMB_MONGODB_AUTH_SOURCE: Database containing the users (default: ‘admin’).
    • HONEYCOMB_MONGODB_AUTH_MODE: Authentication mode used by your Mongodb instance (default: ‘SCRAM-SHA-1’, available values).
  • Use HTTPS, as documented:
    • HONEYCOMB_SSL_KEYSTORE_PATH: Path to the Java keyStore.
    • HONEYCOMB_SSL_KEYSTORE_TYPE: Type of the keystore (default: ‘JKS’).
    • HONEYCOMB_SSL_KEYSTORE_PASSWORD: Password for the java keyStore.
    • HONEYCOMB_SSL_KEYSTORE_ALGORITHM: Algorithm used by the keyStore.

Docker compose example

The following sample will deploy a Honeycomb server listening on port 80 with a linked mongodb database:

honeycomb:
  image: apisense/honeycomb:latest 
  ports:
    - "80:9000"
    - "443:9443" # Enables to contact the Honeycomb via HTTPS
  volumes:
    - "/data/honeycomb/logs:/opt/docker/logs"
  links:
    - database:mongodb
  environment:
    - HONEYCOMB_API_KEY=myKey
  restart: unless-stopped

database:
  image: mongo
  command: "mongod --auth" # This line will activate authentication on Mongodb
  volumes:
    - "/data/honeycomb/mongo:/data/db"
  restart: unless-stopped

You can try it out by saving this content to a docker-compose.yml file and executing the command docker-compose up

Retrieve your data

Access private data

If your crop data are under restricted access, you will have to provide a valid access key to the honeycomb.

To do so, add the following header to your request: Authorization: accessKey $myKey

Get everything

To retrieve the data from your collect, you can click on the button Download data from the dashboard. But you also have access to an API to get the raw json using /api/v1/crop/$cropIdentifier/data.

The Json you will retrieve is built as follow:

[
  {
    "metadata": {
      "timestamp": "2015-10-06T16:00:43+02:00",
      "device": "Android"
    },
    "header": {
      "environmentalInfo": "from sync(...) method, 1 per upload"
    },
    "body": [
      { "yourTrace": "from save(...) method, 1 per trace" },
      { "yourTrace": "another saved trace" },
    ]
  }, {
    ...
  }
]

Filter uploaded data

If you want to insert some specifics, calculated values, you can add a pre-upload filter, applied on each uploaded data (see the section above for the syntax).

// This filter will process every uploaded data
rest.setPreUploadTreatment(function(data) { // data will be the uploaded JSON
   var myUploadedDataArray = data.body;
   var myMetadata = data.metadata;
   myMetadata.count = myUploadedDataArray.length;
   return data; // It is recommended to send back the same json structure as the input.
});

Filter output

If you don’t want to download every collected traces from the server, you can define custom routes to filter the data beforehand.

The creation of these routes can be done in the Filters menu, from the collect dashboard. In this menu, you will find a script editor, in which you can add routes with the following (Javascript) syntax:

// This filter will only return the metadata of each collected trace.
// It can be accessed from the route /api/v1/crop/$cropIdentifier/data/meta
rest.prepareFilter("meta", function(data){ // data will be your raw data json array
  var result = [];
  for each (var ele in data) {
    result.push(ele.metadata);
  }
  return result; // This will be parsed as a Json.
});

After saving your script, you can access the result from the route /api/v1/crop/$cropIdentifier/data/meta.

Retrieve your media

Some stings will record media files (like pictures, sound, or video). For obvious reasons, those media will not directly be saved in the data JSON, but an identifier will be set instead.

Metadata format:

You can retrieve medatada for every media uploaded on a crop from the route /api/v1/crop/$cropIdentifier/media. Every metadata object will contain the following elements:

{
  "cropIdentifier": "Zz86D0v6O1CWGldoD5Zg",
  "identifier": "64C8356C-5C91-48E4-AE5D-E88F3AF047A8",
  "size": 142222,
  "upload": 1455618401229,
  "contentType": "image/jpeg",
  "url": "/api/v1/crop/Zz86D0v6O1CWGldoD5Zg/media/64C8356C-5C91-48E4-AE5D-E88F3AF047A8"
}

With:

  • identifier: Media identifier set in your sting result.
  • size: Media size in bytes.
  • upload: Upload timestamp.
  • contentType: Mime type found by the honeycomb (may be null if the type isn’t recognized).
  • url: Media location on the honeycomb.

Retrieve the media file

A raw media file can be retrieved using the route /api/v1/crop/$cropIdentifier/media/$mediaID, where mediaID is the media identifier set in the sting result.

The file will be sent via an application/octet-stream content type, whichever the file type may be.