{"_id":"56aa38f6befafb1900044ccf","category":{"_id":"56a3e78a94ec0a0d00b39fed","pages":["56a3e79b5e57f20d000eae83","56a3e7c2545bc50d000e3abf","56a3e7da5fb2530d00421b5a","56a9fee32bb3910d000ee9ba","56aa2f502bb3910d000eea00","56aa38f6befafb1900044ccf","56aa38fa2bb3910d000eea0e"],"project":"56a1f77442dfda0d00046285","version":"56a1f77542dfda0d00046288","__v":7,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-23T20:50:18.363Z","from_sync":false,"order":0,"slug":"nodejs","title":"Node.js Monitoring"},"version":{"_id":"56a1f77542dfda0d00046288","__v":9,"project":"56a1f77442dfda0d00046285","createdAt":"2016-01-22T09:33:41.397Z","releaseDate":"2016-01-22T09:33:41.397Z","categories":["56a1f77542dfda0d00046289","56a1fdf442dfda0d00046294","56a2079f0067c00d00a2f955","56a20bdf8b2e6f0d0018ea84","56a3e78a94ec0a0d00b39fed","56af19929d32e30d0006d2ce","5721f4e9dcfa860e005bef98","574e870be892bf0e004fde0d","5832fdcdb32d820f0072e12f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"parentDoc":null,"project":"56a1f77442dfda0d00046285","__v":16,"user":"56a9e5e8ca491e0d00eb8af0","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-28T15:51:18.391Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"## API\n\nOur API documentation is also available on the [Trace collector GitHub](https://github.com/RisingStack/trace-nodejs) repository.\n\n## Sending extra data\n\n### trace.report(name[, data...])\n\nThis method can be used to report additional data to the Trace servers which later on helps with debugging.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Reported data will only show up in a Trace if some kind of an error happened in your transaction.\",\n  \"title\": \"Data context\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"trace.report('name', {\\n  userId: 10\\n})\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The `name` of the report is mandatory *(a string)* and must be unique throughout the whole transaction.\",\n  \"title\": \"Unique report name\"\n}\n[/block]\n### trace.reportError(errorName, Error)\n\nThis method can be used to send errors to the Trace servers. The second argument to the method must be an Error object having a message property.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"trace.reportError('mysql_error', new Error('connection lost'))\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Transactions using this method are not subject to sampling, so they will be collected all the time and shown in the Trace list.\",\n  \"title\": \"Always collected\"\n}\n[/block]\n## Manage transactions\n\n### trace.getTransactionId()\n\nIf you're in the middle of handling an incoming HTTP request, this method can be used to get the unique `request-id` Trace associated with it. It can be useful if you want to integrate Trace with your current logging systems.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var transactionId = trace.getTransactionId()\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Custom metrics\n\nFor our detailed tutorial check out [Custom metrics](doc:custom_metrics).\n\n### trace.recordMetric(name:String, value:Number)\n\nRecord metrics is useful when you **have multiple events** that have a discrete value at a given point of time. \nIt can be used to collect the element count of a queue, the number of open connections or if you are building IoT devices then to collect temperature values.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"trace.recordMetric('order/orderAmount', 412 /* $ */)\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### trace.incrementMetric(name:String, [value:Number])\n\nBy using increment metrics you don't have to keep track of a value over time as you would in record metric, you simply have to call a function and everything will be done automatically. This comes handy when you would like to keep track of occurrences of events.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"trace.incrementMetric('order/gpu', 5)\\ntrace.incrementMetric('order/gpu')\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"api-documentation","type":"basic","title":"API Documentation"}
## API Our API documentation is also available on the [Trace collector GitHub](https://github.com/RisingStack/trace-nodejs) repository. ## Sending extra data ### trace.report(name[, data...]) This method can be used to report additional data to the Trace servers which later on helps with debugging. [block:callout] { "type": "info", "body": "Reported data will only show up in a Trace if some kind of an error happened in your transaction.", "title": "Data context" } [/block] [block:code] { "codes": [ { "code": "trace.report('name', {\n userId: 10\n})", "language": "javascript" } ] } [/block] [block:callout] { "type": "warning", "body": "The `name` of the report is mandatory *(a string)* and must be unique throughout the whole transaction.", "title": "Unique report name" } [/block] ### trace.reportError(errorName, Error) This method can be used to send errors to the Trace servers. The second argument to the method must be an Error object having a message property. [block:code] { "codes": [ { "code": "trace.reportError('mysql_error', new Error('connection lost'))", "language": "text" } ] } [/block] [block:callout] { "type": "info", "body": "Transactions using this method are not subject to sampling, so they will be collected all the time and shown in the Trace list.", "title": "Always collected" } [/block] ## Manage transactions ### trace.getTransactionId() If you're in the middle of handling an incoming HTTP request, this method can be used to get the unique `request-id` Trace associated with it. It can be useful if you want to integrate Trace with your current logging systems. [block:code] { "codes": [ { "code": "var transactionId = trace.getTransactionId()", "language": "javascript" } ] } [/block] ## Custom metrics For our detailed tutorial check out [Custom metrics](doc:custom_metrics). ### trace.recordMetric(name:String, value:Number) Record metrics is useful when you **have multiple events** that have a discrete value at a given point of time. It can be used to collect the element count of a queue, the number of open connections or if you are building IoT devices then to collect temperature values. [block:code] { "codes": [ { "code": "trace.recordMetric('order/orderAmount', 412 /* $ */)", "language": "javascript" } ] } [/block] ### trace.incrementMetric(name:String, [value:Number]) By using increment metrics you don't have to keep track of a value over time as you would in record metric, you simply have to call a function and everything will be done automatically. This comes handy when you would like to keep track of occurrences of events. [block:code] { "codes": [ { "code": "trace.incrementMetric('order/gpu', 5)\ntrace.incrementMetric('order/gpu')", "language": "javascript" } ] } [/block]