Data Enrichment Overview

What is a data enrichment? A data enrichment is a powerful add-on to enrich the data you’re already streaming to Keen.

At Keen we enable the ability for you to do some pre-processing of the data streams in a few ways. To make things easier for you we’ve created a few common enrichments that are useful to customers.

You can find more documentation on each of these indivdual enrichments here:

Configure with an IP address:

{
  "ip_address" : "${keen.ip}",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:ip_to_geo",
        "input" : {
          "ip" : "ip_address"
        },
        "output" : "ip_geo_info"
      }
    ]
  }
}

This example uses the ${keen.ip} placeholder, but standard IP addresses work too. Learn more about dynamic placeholders in the API reference.

We’ll fill in geographic information:

{
  "ip_address" : "192.168.0.1",
  "ip_geo_info" : {
    "city" : "San Francisco",
    "province" : "California",
    "country" : "United States",
    "continent" : "North America",
    "postal_code" : "94122",
    "coordinates" : [-122.42005, 37.77479]
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with a user agent string:

{
  "user_agent" : "${keen.user_agent}",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:ua_parser",
        "input" : {
          "ua_string" : "user_agent"
        },
        "output" : "parsed_user_agent"
      }
    ]
  }
}

This example uses the ${keen.user_agent} placeholder, but standard user agent strings work too. Learn more about dynamic placeholders in the API reference.

We’ll fill in available information:

{
  "user_agent": "Mozilla/5.0 (iPhone; U; CPU iPhone OS 5_1_1 like Mac OS X; en AppleWebKit/534.46.0 (KHTML, like Gecko) CriOS/19.0.1084.60 Mobile/9B206 Safari/7534.48.3",
  "parsed_user_agent" : {
    "device" : {
      "family" : "iPhone",
      "type": "mobile phone"
    },
    "browser" : {
      "family" : "Chrome Mobile iOS",
      "major" : 19,
      "minor" : 0,
      "patch" : 1084
    },
    "os" : {
      "family" : "iOS",
      "major" : 5 ,
      "minor" : 1,
      "patch" : 1,
      "patch_minor" : null
    }
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with a URL:

{
  "page_url" : "http://my-website.com/cool/link?source=twitter&foo=bar/#title",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:url_parser",
        "input" : {
          "url" : "page_url"
        },
        "output" : "parsed_page_url"
      }
    ]
  }
}

Missing URL elements, such as a query string or anchor, will be omitted from the recorded output object.

We’ll parse the URL into queryable pieces:

{
  "page_url" : "http://my-website.com/cool/link?source=twitter&foo=bar/#title",
  "parsed_page_url": {
    "protocol" : "http",
    "domain" : "my-website.com",
    "path" : "/cool/link",
    "anchor" : "title",
    "query_string" : {
      "source" : "twitter",
      "foo" : "bar"
    }
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with page and referrer URLs:

{
  "referrer" : {
    "url": "https://search.com?search=analytics"
  },
  "page_url": "http://mysite.com/landing-page",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:referrer_parser",
        "input" : {
          "referrer_url" : "referrer.url",
          "page_url" : "page_url"
        },
        "output" : "referrer.info"
      }
    ]
  }
}

Mal-formed page_url or referrer_url input parameters will result in blank output values.

We’ll parse the referrer into its source:

{
  "referrer": {
    "url": "https://search.com?search=analytics",
    "info": {
      "medium" : "SEARCH",
      "source" : "search.com",
      "term" : "analytics"
    }
  },
  "page_url": "http://mysite.com/landing-page"
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with a datetime property:

{
  "keen" : {
    "timestamp": "2016-05-21T16:36:40.092Z"
    "addons": [
      {
        "name": "keen:date_time_parser",
        "input": {
          "date_time": "keen.timestamp",

        },
        "output": "timestamp_info"
      }
    ]
  }
}

This example uses the keen.timestamp property, but this will work with any property that looks like a datetime.

We’ll fill in datetime information:

{
  "keen": {
    "timestamp": "2016-05-21T16:36:40.092Z"
  },
  "timestamp_info": {
    "millisecond": 92,
    "day_of_week_string": "Saturday",
    "hour": 16,
    "timezone_offset": 0,
    "day_of_month": 21,
    "day_of_week": 6,
    "month": 5,
    "second": 40,
    "week": 20,
    "year": 2016,
    "minute": 36
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.