{"_id":"56c41cad4f0aed1700afabaa","__v":5,"project":"56bc8e679afb8b0d00d62dcf","user":"56b98db7bb36440d0001f492","version":{"_id":"56bc8e689afb8b0d00d62dd2","project":"56bc8e679afb8b0d00d62dcf","__v":18,"createdAt":"2016-02-11T13:36:40.146Z","releaseDate":"2016-02-11T13:36:40.146Z","categories":["56bc8e689afb8b0d00d62dd3","56c3c837bc41330d009f25ed","56c3c83e521f350d00d348eb","56c3c8452d97560d00e23cd8","56c3c85234df460d00c2beb8","56c4180d70187b17005f43b4","56c418162d97560d00e23cf6","56c4181cc4796b0d007ef039","56c4182370187b17005f43b5","56c418292e75e01700986052","56c4183328bd680d005e7ac6","56c4183bbb64720d00552b88","56c418414040602b0064cea0","56c4184754b6030d00ec29a1","56c4184c28bd680d005e7ac7","56c4185370187b17005f43b6","56c4185b6063071700500cfc","582a98b6f8c0a0190053d7a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"56c4183328bd680d005e7ac6","pages":["56c41c94106c12170020dba2","56c41ca22d97560d00e23cfd","56c41cad4f0aed1700afabaa","56c41cb670187b17005f43bd"],"project":"56bc8e679afb8b0d00d62dcf","__v":4,"version":"56bc8e689afb8b0d00d62dd2","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-02-17T06:50:27.750Z","from_sync":false,"order":1,"slug":"iot-telemetry","title":"IoT Telemetry"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-17T07:09:33.347Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"/telemetry/{name}\"\n}\n[/block]\nMake sure you've read the [Telemetry Overview](doc:telemetry-overview)!\n\nBefore you can [send telemetry data](doc:add-telemetry-data), you need to tell Buddy a little bit about it by creating a **Telemetry Configuration**. \n\nThis configuration can be overwritten any number of times, even with the same values, so if you're going to be sending telemetry data, go ahead and call this method before you send your first data batch. Or you can call it when the app first initializes, then use metadata to flag that you've created the configuration.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Be sure to use the 'put' method to configure your telemetry.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var options = {\\n\\tsamplingRate: 50,\\n\\tuniqueIdKey: \\\"some.id\\\",\\n\\tfilterKeys: \\\"['sensitive.info', 'more.sensitive.info', 'useless.value']\\\",\\n\\trequireKeys: \\\"['my.important.info', 'some.validation']\\\",\\n\\tmetrics: \\\"{'usage': 'usage', 'info_mode': 'info.mode'}\\\",\\n\\ttestData: \\\"{'sensitive': {'info': 'Very secure', 'id': 'hjWER12'}, 'more':{'sensitive': {'info': 55}, 'open': 'true'}}\\\",\\n\\tprojection: \\\"{}\\\",\\n\\tlifetimeInMinutes: 60\\n};\\n\\nBuddy.put('/telemetry/my_name',\\n\\t\\toptions,\\n\\t\\tfunction(err, result) {\\n\\t\\t\\t \\n\\t\\t\\tif (result.success) {\\n\\t\\t\\t\\t// Do something with the result!\\n\\t\\t\\t} else { \\n\\t\\t\\t\\t// Otherwise log the error\\n\\t\\t\\t\\tconsole.log(err); \\n\\t\\t\\t} \\n\\t\\t}\\n\\t);\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"NSDictionary *params = :::at:::{\\n\\t\\t\\[email protected]\\\"samplingRate\\\": 50,\\n\\t\\t\\[email protected]\\\"uniqueIdKey\\\": @\\\"some.id\\\",\\n\\t\\t\\[email protected]\\\"filterKeys\\\": @\\\"['sensitive.info', 'more.sensitive.info', 'useless.value']\\\",\\n\\t\\t\\[email protected]\\\"requireKeys\\\": @\\\"['my.important.info', 'some.validation']\\\",\\n\\t\\t\\[email protected]\\\"metrics\\\": @\\\"{'usage': 'usage', 'info_mode': 'info.mode'}\\\",\\n\\t\\t\\[email protected]\\\"testData\\\": @\\\"{'sensitive': {'info': 'Very secure', 'id': 'hjWER12'}, 'more':{'sensitive': {'info': 55}, 'open': 'true'}}\\\",\\n\\t\\t\\[email protected]\\\"projection\\\": @\\\"{}\\\",\\n\\t\\t\\[email protected]\\\"lifetimeInMinutes\\\": 60\\n\\t\\t};\\n\\n[Buddy PUT:@\\\"/telemetry/my_name\\\" parameters:params class:[NSNumber class] callback:^(id obj, NSError *error) {\\n\\t// Your callback code here\\n}];\",\n      \"language\": \"objectivec\",\n      \"name\": \"iOS\"\n    },\n    {\n      \"code\": \"Map<String, Object> parameters = new HashMap<String, Object>();\\nparameters.put(\\\"samplingRate\\\", 50);\\nparameters.put(\\\"uniqueIdKey\\\", \\\"some.id\\\");\\nparameters.put(\\\"filterKeys\\\", \\\"['sensitive.info', 'more.sensitive.info', 'useless.value']\\\");\\nparameters.put(\\\"requireKeys\\\", \\\"['my.important.info', 'some.validation']\\\");\\nparameters.put(\\\"metrics\\\", \\\"{'usage': 'usage', 'info_mode': 'info.mode'}\\\");\\nparameters.put(\\\"testData\\\", \\\"{'sensitive': {'info': 'Very secure', 'id': 'hjWER12'}, 'more':{'sensitive': {'info': 55}, 'open': 'true'}}\\\");\\nparameters.put(\\\"projection\\\", \\\"{}\\\");\\nparameters.put(\\\"lifetimeInMinutes\\\", 60);\\n\\nBuddy.<Boolean>put(\\\"/telemetry/my_name\\\", parameters, new BuddyCallback<Boolean>(Boolean.class) {\\n\\[email protected]\\n\\tpublic void completed(BuddyResult<Boolean> result) {\\n\\t\\t// Your callback code here\\n\\t}\\n});\",\n      \"language\": \"java\",\n      \"name\": \"Android\"\n    },\n    {\n      \"code\": \"var options = new {\\n\\t\\t\\tsamplingRate = 50,\\n\\t\\t\\tuniqueIdKey = \\\"some.id\\\",\\n\\t\\t\\tfilterKeys = \\\"['sensitive.info', 'more.sensitive.info', 'useless.value']\\\",\\n\\t\\t\\trequireKeys = \\\"['my.important.info', 'some.validation']\\\",\\n\\t\\t\\tmetrics = \\\"{'usage': 'usage', 'info_mode': 'info.mode'}\\\",\\n\\t\\t\\ttestData = new {sensitive = new {info = 'Very secure', id = 'hjWER12'}, more = new {sensitive = new {info: 55}, open= true}},\\n\\t\\t\\tprojection = \\\"{}\\\",\\n\\t\\t\\tlifetimeInMinutes = 60\\n\\t\\t};\\n\\nvar result = await Buddy.PutAsync<bool>(\\\"/telemetry/my_name\\\", options);\",\n      \"language\": \"csharp\",\n      \"name\": \".NET\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n###Path Parameters\n\nThese parameters should be specified as part of the HTTP path.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"name\",\n    \"0-1\": \"The name of the configuration to create or update.\",\n    \"0-2\": \"string\",\n    \"0-3\": \"Required\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n###Body Parameters\n\nThese parameters should be specified as part of the request body.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"samplingRate\",\n    \"0-1\": \"A number describing what percentage of the data to store, with 0 being none and 100 being all data.\",\n    \"1-0\": \"uniqueIdKey\",\n    \"1-1\": \"A path key describing what data value should be treated as the unique identifier for a piece of telemetry data. For example, if a data send was as follows:\\n```\\n{\\n  id: 'ABC-123',\\n  info: {\\n      serial: '123-456'\\n  },\\n  value: 214\\n}\\n```\\nThen passing the value id would result in the unique ID ABC-123 being captured. Conversely, passing info.serial, would result in 123-456 being captured.\",\n    \"2-0\": \"filterKeys\",\n    \"3-0\": \"requireKeys\",\n    \"4-0\": \"metrics\",\n    \"5-0\": \"testData\",\n    \"6-0\": \"projection\",\n    \"7-0\": \"lifetimeInMinutes\",\n    \"2-1\": \"A set of key paths, passed as an array, describing keys to be removed from telemetry data. Use this to remove customer sensitive information.\",\n    \"3-1\": \"A set of key paths, passed as an array, describing keys that must be present for the data to be valid. If data is passed without one or more of these keys being present, it is ignored.\",\n    \"4-1\": \"A JSON object describing which values in the telemetry data to convert to Buddy Metrics.\\n\\nFor example, with configuration as:\\n```\\n metrics: {\\n     'usage': 'usage',\\n     'info_mode' : 'info.mode'\\n }\\n```\\nwith data like:\\n```\\n { \\n   id: 123,\\n   usage: 38,\\n   info: {\\n     mode: 7,\\n     data: 'some info'\\n   }\\n }\\n```\\nTwo metrics would be registered, one called usage with value of 38, and one called info_mode with a value of 7.\",\n    \"5-1\": \"If specified, a data item to apply this configuration to. No actual storage or metrics will occur but the return value will contain JSON describing how Buddy would transform the data. This allows you to test your configurations without sending real data.\",\n    \"6-1\": \"Describes the projection of the data onto the telemetry object.\",\n    \"7-1\": \"The lifetime of this telemetry object.\",\n    \"0-2\": \"number\",\n    \"1-2\": \"string\",\n    \"2-2\": \"string\",\n    \"3-2\": \"string\",\n    \"6-2\": \"string\",\n    \"5-2\": \"string\",\n    \"7-2\": \"number\",\n    \"4-2\": \"object\",\n    \"0-3\": \"Optional\",\n    \"1-3\": \"Optional\",\n    \"2-3\": \"Optional\",\n    \"3-3\": \"Optional\",\n    \"4-3\": \"Optional\",\n    \"5-3\": \"Optional\",\n    \"6-3\": \"Optional\",\n    \"7-3\": \"Optional\"\n  },\n  \"cols\": 4,\n  \"rows\": 8\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"status\\\": 200,\\n    \\\"result\\\": {\\n        \\\"timestamp\\\": \\\"/Date(1393604401353)/\\\",\\n        \\\"data\\\": {\\n            \\\"info\\\": {\\n                \\\"stuff\\\": \\\"hello\\\",\\n                \\\"speed\\\": 12\\n            }\\n        },\\n        \\\"unique_id\\\": 23432,\\n        \\\"metrics\\\": {\\n            \\\"speed\\\": {\\n                \\\"value\\\": 12\\n            }\\n        }\\n    },\\n    \\\"request_id\\\": \\\"55a807e4-abc7-4868-8315-6981d4469fd2\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"configure-telemetry","type":"basic","title":"Configure Telemetry"}

Configure Telemetry


[block:api-header] { "type": "put", "title": "/telemetry/{name}" } [/block] Make sure you've read the [Telemetry Overview](doc:telemetry-overview)! Before you can [send telemetry data](doc:add-telemetry-data), you need to tell Buddy a little bit about it by creating a **Telemetry Configuration**. This configuration can be overwritten any number of times, even with the same values, so if you're going to be sending telemetry data, go ahead and call this method before you send your first data batch. Or you can call it when the app first initializes, then use metadata to flag that you've created the configuration. [block:callout] { "type": "info", "body": "Be sure to use the 'put' method to configure your telemetry." } [/block] [block:code] { "codes": [ { "code": "var options = {\n\tsamplingRate: 50,\n\tuniqueIdKey: \"some.id\",\n\tfilterKeys: \"['sensitive.info', 'more.sensitive.info', 'useless.value']\",\n\trequireKeys: \"['my.important.info', 'some.validation']\",\n\tmetrics: \"{'usage': 'usage', 'info_mode': 'info.mode'}\",\n\ttestData: \"{'sensitive': {'info': 'Very secure', 'id': 'hjWER12'}, 'more':{'sensitive': {'info': 55}, 'open': 'true'}}\",\n\tprojection: \"{}\",\n\tlifetimeInMinutes: 60\n};\n\nBuddy.put('/telemetry/my_name',\n\t\toptions,\n\t\tfunction(err, result) {\n\t\t\t \n\t\t\tif (result.success) {\n\t\t\t\t// Do something with the result!\n\t\t\t} else { \n\t\t\t\t// Otherwise log the error\n\t\t\t\tconsole.log(err); \n\t\t\t} \n\t\t}\n\t);", "language": "javascript" }, { "code": "NSDictionary *params = @{\n\t\t\[email protected]\"samplingRate\": 50,\n\t\t\[email protected]\"uniqueIdKey\": @\"some.id\",\n\t\t\[email protected]\"filterKeys\": @\"['sensitive.info', 'more.sensitive.info', 'useless.value']\",\n\t\t\[email protected]\"requireKeys\": @\"['my.important.info', 'some.validation']\",\n\t\t\[email protected]\"metrics\": @\"{'usage': 'usage', 'info_mode': 'info.mode'}\",\n\t\t\[email protected]\"testData\": @\"{'sensitive': {'info': 'Very secure', 'id': 'hjWER12'}, 'more':{'sensitive': {'info': 55}, 'open': 'true'}}\",\n\t\t\[email protected]\"projection\": @\"{}\",\n\t\t\[email protected]\"lifetimeInMinutes\": 60\n\t\t};\n\n[Buddy PUT:@\"/telemetry/my_name\" parameters:params class:[NSNumber class] callback:^(id obj, NSError *error) {\n\t// Your callback code here\n}];", "language": "objectivec", "name": "iOS" }, { "code": "Map<String, Object> parameters = new HashMap<String, Object>();\nparameters.put(\"samplingRate\", 50);\nparameters.put(\"uniqueIdKey\", \"some.id\");\nparameters.put(\"filterKeys\", \"['sensitive.info', 'more.sensitive.info', 'useless.value']\");\nparameters.put(\"requireKeys\", \"['my.important.info', 'some.validation']\");\nparameters.put(\"metrics\", \"{'usage': 'usage', 'info_mode': 'info.mode'}\");\nparameters.put(\"testData\", \"{'sensitive': {'info': 'Very secure', 'id': 'hjWER12'}, 'more':{'sensitive': {'info': 55}, 'open': 'true'}}\");\nparameters.put(\"projection\", \"{}\");\nparameters.put(\"lifetimeInMinutes\", 60);\n\nBuddy.<Boolean>put(\"/telemetry/my_name\", parameters, new BuddyCallback<Boolean>(Boolean.class) {\n\[email protected]\n\tpublic void completed(BuddyResult<Boolean> result) {\n\t\t// Your callback code here\n\t}\n});", "language": "java", "name": "Android" }, { "code": "var options = new {\n\t\t\tsamplingRate = 50,\n\t\t\tuniqueIdKey = \"some.id\",\n\t\t\tfilterKeys = \"['sensitive.info', 'more.sensitive.info', 'useless.value']\",\n\t\t\trequireKeys = \"['my.important.info', 'some.validation']\",\n\t\t\tmetrics = \"{'usage': 'usage', 'info_mode': 'info.mode'}\",\n\t\t\ttestData = new {sensitive = new {info = 'Very secure', id = 'hjWER12'}, more = new {sensitive = new {info: 55}, open= true}},\n\t\t\tprojection = \"{}\",\n\t\t\tlifetimeInMinutes = 60\n\t\t};\n\nvar result = await Buddy.PutAsync<bool>(\"/telemetry/my_name\", options);", "language": "csharp", "name": ".NET" } ], "sidebar": true } [/block] ###Path Parameters These parameters should be specified as part of the HTTP path. [block:parameters] { "data": { "0-0": "name", "0-1": "The name of the configuration to create or update.", "0-2": "string", "0-3": "Required" }, "cols": 4, "rows": 1 } [/block] ###Body Parameters These parameters should be specified as part of the request body. [block:parameters] { "data": { "0-0": "samplingRate", "0-1": "A number describing what percentage of the data to store, with 0 being none and 100 being all data.", "1-0": "uniqueIdKey", "1-1": "A path key describing what data value should be treated as the unique identifier for a piece of telemetry data. For example, if a data send was as follows:\n```\n{\n id: 'ABC-123',\n info: {\n serial: '123-456'\n },\n value: 214\n}\n```\nThen passing the value id would result in the unique ID ABC-123 being captured. Conversely, passing info.serial, would result in 123-456 being captured.", "2-0": "filterKeys", "3-0": "requireKeys", "4-0": "metrics", "5-0": "testData", "6-0": "projection", "7-0": "lifetimeInMinutes", "2-1": "A set of key paths, passed as an array, describing keys to be removed from telemetry data. Use this to remove customer sensitive information.", "3-1": "A set of key paths, passed as an array, describing keys that must be present for the data to be valid. If data is passed without one or more of these keys being present, it is ignored.", "4-1": "A JSON object describing which values in the telemetry data to convert to Buddy Metrics.\n\nFor example, with configuration as:\n```\n metrics: {\n 'usage': 'usage',\n 'info_mode' : 'info.mode'\n }\n```\nwith data like:\n```\n { \n id: 123,\n usage: 38,\n info: {\n mode: 7,\n data: 'some info'\n }\n }\n```\nTwo metrics would be registered, one called usage with value of 38, and one called info_mode with a value of 7.", "5-1": "If specified, a data item to apply this configuration to. No actual storage or metrics will occur but the return value will contain JSON describing how Buddy would transform the data. This allows you to test your configurations without sending real data.", "6-1": "Describes the projection of the data onto the telemetry object.", "7-1": "The lifetime of this telemetry object.", "0-2": "number", "1-2": "string", "2-2": "string", "3-2": "string", "6-2": "string", "5-2": "string", "7-2": "number", "4-2": "object", "0-3": "Optional", "1-3": "Optional", "2-3": "Optional", "3-3": "Optional", "4-3": "Optional", "5-3": "Optional", "6-3": "Optional", "7-3": "Optional" }, "cols": 4, "rows": 8 } [/block] [block:code] { "codes": [ { "code": "{\n \"status\": 200,\n \"result\": {\n \"timestamp\": \"/Date(1393604401353)/\",\n \"data\": {\n \"info\": {\n \"stuff\": \"hello\",\n \"speed\": 12\n }\n },\n \"unique_id\": 23432,\n \"metrics\": {\n \"speed\": {\n \"value\": 12\n }\n }\n },\n \"request_id\": \"55a807e4-abc7-4868-8315-6981d4469fd2\"\n}", "language": "json", "name": "Response" } ], "sidebar": true } [/block]