{"_id":"56a3e7c2545bc50d000e3abf","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"},"project":"56a1f77442dfda0d00046285","user":"56a1f82b06150b0d002ad173","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"},"__v":45,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-23T20:51:14.736Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"## User sent events\n\nUser sent events enable you to send arbitrary content to Trace during a transaction. This should be information you consider important to monitor or helps you later with debugging. This functionality is available through the [API](doc:api-documentation).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// index.js\\nvar trace = require(':::at:::risingstack/trace')\\n\\nvar app = require('express')()\\n\\napp.get('/', function (req, res) {\\n  trace.report('user-agent', {\\n    userAgent: req.headers['user-agent']\\n  })\\n  res.send('hello')\\n})\\n\\napp.listen(3000)\",\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 service name\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Trace associates every data received from the client with transaction spans. This also applies to user sent events, which means that `trace.report` MUST be called inside a transaction to have any effect.\",\n  \"title\": \"Transactions\"\n}\n[/block]\nBy default Trace only collect transactions which has some kind of an error inside them - to trigger manual collection of given Traces you can send the `x-must-collect` HTTP header to the service you call. The value of the header can be anything.\n\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"As of now Trace supports only HTTP based microservices - message queue support is a work in progress.\",\n  \"title\": \"Communication protocol\"\n}\n[/block]\n## Configuring from file\n\nMost options can be configured with their corresponding environment variables, but should you require total control you have to use a configuration file, as some are only exposed there. We look for a file named `trace.config.js` in your current working directory by default. Having it is optional, but if found we will try to load it.\nWhen something is specified in multiple locations we resolve them according to the following order of precedence:\n1. Environment variables take topmost priority.\n2. If an option isn't specified there, we try to read it from the config file.\n3. As the last resort, we check it in our defaults.\n\nThe config file is an ordinary Node.js module that exports a single object, called the *configuration object*. It should contain a combination of properties you wish to configure.\n\nHere's an example `trace.config.js` file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"module.exports = {\\n  serviceName: 'your-awesome-app',\\n  apiKey: 'KEEP_ME_SECRET',\\n  ignoreHeaders: {\\n    'user-agent': [\\n      'Varnish/fastly (healthcheck)'\\n    ]\\n  },\\n  ignorePaths: [\\n    '/healthcheck'\\n  ],\\n  ignoreStatusCodes: [\\n  \\t401,\\n    404\\n  ],\\n  ignoreOutgoingHosts: [\\n    'google.com'\\n  ],\\n  disableInstrumentations: [\\n    'mongodb'\\n  ],\\n  proxy: 'http://168.63.76.32:3128'\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Here please pay special attention to the `ignoreHeaders` option. With this, you can specify which requests should not be accounted. This can be extremely useful if you want to filter out the noise generated by your health checks for example.\",\n  \"title\": \"Ignore specific headers\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you want to place the config file elsewhere, you can do it with the help of an environment variable:\\n`TRACE_CONFIG_PATH=/path/to/config.js`\",\n  \"title\": \"Config file path\"\n}\n[/block]\n## Available options\n\nHere's the complete list of options that are exposed to environment variables, configuration properties, or both.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Environment variable\",\n    \"h-1\": \"Config property\",\n    \"h-2\": \"Type\",\n    \"0-0\": \"TRACE_API_KEY\",\n    \"1-0\": \"TRACE_SERVICE_NAME\",\n    \"2-0\": \"TRACE_CONFIG_PATH\",\n    \"1-1\": \"serviceName\",\n    \"0-1\": \"apiKey\",\n    \"0-2\": \"string\",\n    \"1-2\": \"string\",\n    \"2-2\": \"string\",\n    \"2-1\": \"\",\n    \"h-3\": \"Description\",\n    \"0-3\": \"The API key of the project you want to include this service\",\n    \"1-3\": \"Unique name for your service within the project\",\n    \"2-3\": \"Custom configuration path. Relative paths are resolved from the current working directory\",\n    \"h-4\": \"Defaults\",\n    \"0-4\": \"Nothing. Trace will stop with an error.\",\n    \"1-4\": \"Nothing. Trace will stop with an error.\",\n    \"2-4\": \"trace.config.js\",\n    \"5-0\": \"TRACE_DISABLE_INSTRUMENTATIONS\",\n    \"5-1\": \"disableInstrumentations\",\n    \"5-2\": \"Contrary to the above, it has two different syntaxes.  For the environment variable: comma-separated string\\nFor the config file property:\\nJSON array of strings\",\n    \"5-3\": \"Allows module instrumentations to be disabled by their name. See the list of [instrumented libraries](doc:supported-packages).\",\n    \"6-0\": \"TRACE_DISABLE_STACK_TRACE\",\n    \"6-1\": \"disableStackTrace\",\n    \"6-2\": \"boolean\",\n    \"6-3\": \"when set to true, it prohibits Trace from sending stack traces\",\n    \"7-0\": \"TRACE_PROXY\",\n    \"7-1\": \"proxy\",\n    \"7-2\": \"string\",\n    \"7-3\": \"the location of the proxy Trace should use\",\n    \"8-0\": \"TRACE_KEEP_QUERY_PARAMS\",\n    \"8-1\": \"keepQueryParams\",\n    \"8-2\": \"boolean\",\n    \"8-3\": \"if true, the Tracer agent will record the query parameters of the incoming HTTP requests as part of the traces\",\n    \"5-4\": \"empty array\",\n    \"6-4\": \"false\",\n    \"7-4\": \"empty string\",\n    \"8-4\": \"false\",\n    \"h-5\": \"Availability\",\n    \"8-5\": \"from 3.1.0\",\n    \"7-5\": \"from 2.28.0\",\n    \"6-5\": \"from 2.21.0\",\n    \"5-5\": \"from 2.16.0\",\n    \"4-0\": \"TRACE_IGNORE_OUTGOUNG_HOSTS\",\n    \"4-1\": \"ignoreOutgoingHosts\",\n    \"4-2\": \"JSON array of strings\",\n    \"4-5\": \"from 2.15.0\",\n    \"4-4\": \"singleton array containing TRACE_COLLECTOR_API_URL\",\n    \"4-3\": \"Trace will ignore reporting transactions that are sent to the specified hosts. Note: to prevent littering the transactions with the ones that Trace itself makes with the API, the TRACE_COLLECTOR_API_URL is always appended to the  list.\",\n    \"3-0\": \"TRACE_COLLECTOR_API_URL\",\n    \"3-1\": \"collectorApiUrl\",\n    \"3-2\": \"string\",\n    \"3-3\": \"The URL of the Trace API. Normally you don't have to override the default value.\",\n    \"3-4\": \"https://trace-collector-api.risingstack.com\",\n    \"9-0\": \"TRACE_PROFILER_WINDOW_LENGTH\",\n    \"9-1\": \"profilerWindowLength\",\n    \"9-2\": \"number\",\n    \"9-3\": \"The number of milliseconds the CPU profiler should run.\",\n    \"9-4\": \"10000\",\n    \"9-5\": \"from 3.8.0\"\n  },\n  \"cols\": 6,\n  \"rows\": 10\n}\n[/block]","excerpt":"","slug":"advanced-usage","type":"basic","title":"Advanced usage"}
## User sent events User sent events enable you to send arbitrary content to Trace during a transaction. This should be information you consider important to monitor or helps you later with debugging. This functionality is available through the [API](doc:api-documentation). [block:code] { "codes": [ { "code": "// index.js\nvar trace = require('@risingstack/trace')\n\nvar app = require('express')()\n\napp.get('/', function (req, res) {\n trace.report('user-agent', {\n userAgent: req.headers['user-agent']\n })\n res.send('hello')\n})\n\napp.listen(3000)", "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 service name" } [/block] [block:callout] { "type": "warning", "body": "Trace associates every data received from the client with transaction spans. This also applies to user sent events, which means that `trace.report` MUST be called inside a transaction to have any effect.", "title": "Transactions" } [/block] By default Trace only collect transactions which has some kind of an error inside them - to trigger manual collection of given Traces you can send the `x-must-collect` HTTP header to the service you call. The value of the header can be anything. [block:callout] { "type": "info", "body": "As of now Trace supports only HTTP based microservices - message queue support is a work in progress.", "title": "Communication protocol" } [/block] ## Configuring from file Most options can be configured with their corresponding environment variables, but should you require total control you have to use a configuration file, as some are only exposed there. We look for a file named `trace.config.js` in your current working directory by default. Having it is optional, but if found we will try to load it. When something is specified in multiple locations we resolve them according to the following order of precedence: 1. Environment variables take topmost priority. 2. If an option isn't specified there, we try to read it from the config file. 3. As the last resort, we check it in our defaults. The config file is an ordinary Node.js module that exports a single object, called the *configuration object*. It should contain a combination of properties you wish to configure. Here's an example `trace.config.js` file: [block:code] { "codes": [ { "code": "module.exports = {\n serviceName: 'your-awesome-app',\n apiKey: 'KEEP_ME_SECRET',\n ignoreHeaders: {\n 'user-agent': [\n 'Varnish/fastly (healthcheck)'\n ]\n },\n ignorePaths: [\n '/healthcheck'\n ],\n ignoreStatusCodes: [\n \t401,\n 404\n ],\n ignoreOutgoingHosts: [\n 'google.com'\n ],\n disableInstrumentations: [\n 'mongodb'\n ],\n proxy: 'http://168.63.76.32:3128'\n}", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "body": "Here please pay special attention to the `ignoreHeaders` option. With this, you can specify which requests should not be accounted. This can be extremely useful if you want to filter out the noise generated by your health checks for example.", "title": "Ignore specific headers" } [/block] [block:callout] { "type": "info", "body": "If you want to place the config file elsewhere, you can do it with the help of an environment variable:\n`TRACE_CONFIG_PATH=/path/to/config.js`", "title": "Config file path" } [/block] ## Available options Here's the complete list of options that are exposed to environment variables, configuration properties, or both. [block:parameters] { "data": { "h-0": "Environment variable", "h-1": "Config property", "h-2": "Type", "0-0": "TRACE_API_KEY", "1-0": "TRACE_SERVICE_NAME", "2-0": "TRACE_CONFIG_PATH", "1-1": "serviceName", "0-1": "apiKey", "0-2": "string", "1-2": "string", "2-2": "string", "2-1": "", "h-3": "Description", "0-3": "The API key of the project you want to include this service", "1-3": "Unique name for your service within the project", "2-3": "Custom configuration path. Relative paths are resolved from the current working directory", "h-4": "Defaults", "0-4": "Nothing. Trace will stop with an error.", "1-4": "Nothing. Trace will stop with an error.", "2-4": "trace.config.js", "5-0": "TRACE_DISABLE_INSTRUMENTATIONS", "5-1": "disableInstrumentations", "5-2": "Contrary to the above, it has two different syntaxes. For the environment variable: comma-separated string\nFor the config file property:\nJSON array of strings", "5-3": "Allows module instrumentations to be disabled by their name. See the list of [instrumented libraries](doc:supported-packages).", "6-0": "TRACE_DISABLE_STACK_TRACE", "6-1": "disableStackTrace", "6-2": "boolean", "6-3": "when set to true, it prohibits Trace from sending stack traces", "7-0": "TRACE_PROXY", "7-1": "proxy", "7-2": "string", "7-3": "the location of the proxy Trace should use", "8-0": "TRACE_KEEP_QUERY_PARAMS", "8-1": "keepQueryParams", "8-2": "boolean", "8-3": "if true, the Tracer agent will record the query parameters of the incoming HTTP requests as part of the traces", "5-4": "empty array", "6-4": "false", "7-4": "empty string", "8-4": "false", "h-5": "Availability", "8-5": "from 3.1.0", "7-5": "from 2.28.0", "6-5": "from 2.21.0", "5-5": "from 2.16.0", "4-0": "TRACE_IGNORE_OUTGOUNG_HOSTS", "4-1": "ignoreOutgoingHosts", "4-2": "JSON array of strings", "4-5": "from 2.15.0", "4-4": "singleton array containing TRACE_COLLECTOR_API_URL", "4-3": "Trace will ignore reporting transactions that are sent to the specified hosts. Note: to prevent littering the transactions with the ones that Trace itself makes with the API, the TRACE_COLLECTOR_API_URL is always appended to the list.", "3-0": "TRACE_COLLECTOR_API_URL", "3-1": "collectorApiUrl", "3-2": "string", "3-3": "The URL of the Trace API. Normally you don't have to override the default value.", "3-4": "https://trace-collector-api.risingstack.com", "9-0": "TRACE_PROFILER_WINDOW_LENGTH", "9-1": "profilerWindowLength", "9-2": "number", "9-3": "The number of milliseconds the CPU profiler should run.", "9-4": "10000", "9-5": "from 3.8.0" }, "cols": 6, "rows": 10 } [/block]