Name: beeline-nodejs
Owner: Honeycomb
Description: Automatic Honeycomb instrumentation for node.js applications
Created: 2018-01-21 03:32:10.0
Updated: 2018-05-08 23:25:16.0
Pushed: 2018-05-08 23:25:14.0
Homepage: https://honeycomb.io
Size: 343
Language: JavaScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This package instruments your Express/NodeJS application for use with Honeycomb. Slice and dice requests by endpoint, status, or even User ID, with zero custom instrumentation required(1).
Requires Node 8+. Sign up for a Honeycomb trial to obtain a Write Key before starting.
If you've got a NodeJS express
app, you can get request-level instrumentation of Express and other packages you use, magically.
Start by installing this package:
install --save honeycomb-beeline
And adding this to the top of your app.js
before require
/import
ing of other packages:
ire("honeycomb-beeline")({
iteKey: "YOUR-WRITE-KEY",
... additional optional configuration ... */
The optional configuration
above allows configuring global settings (Honeycomb credentials and dataset name) as well as per-instrumentation settings:
writeKey: "/* your honeycomb write key, required */",
dataset: "/* the name of the dataset you want to use (defaults to "nodejs") */"
$instrumentationName: {
/* instrumentation specific settings */
}
Both writeKey
and dataset
can also be supplied in the environment, by setting HONEYCOMB_WRITEKEY
and HONEYCOMB_DATASET
, respectively.
For instrumentation settings, use the name of the instrumentation. For example, to add configuration options for express
, your config object might look like:
writeKey: "1234567890asbcdef",
dataset: "my-express-server",
express: {
/* express-specific settings */
}
For available configuration options per instrumentation, see the Instrumented packages section below.
KDOWN: request.url
ULATE: P99(duration_ms)
ER: meta.type == express
R BY: P99(duration_ms) DESC
KDOWN: meta.type
ULATE: P99(duration_ms)
R BY: P99(duration_ms) DESC
KDOWN: request.user.email
ULATE: COUNT
ER: request.url == <endpoint-url>
KDOWN: request.url
ULATE: P99(duration_ms)
ER: meta.type == express AND request.xhr == true
R BY: P99(duration_ms) DESC
imestamp": "2018-03-20T00:47:25.339Z",
equest.base_url": "",
equest.fresh": false,
equest.host": "localhost",
equest.http_version": "HTTP/1.1",
equest.remote_addr": "127.0.0.1",
equest.method": "POST",
equest.original_url": "/checkValid",
equest.path": "/checkValid",
equest.scheme": "http",
equest.query": "{}",
equest.secure": false,
equest.url": "/checkValid",
equest.xhr": true,
esponse.status_code": "200",
eta.instrumentation_count": 4,
eta.instrumentations": "[\"child_process\",\"express\",\"http\",\"https\"]",
eta.type": "express"
eta.version": "4.16.3",
eta.beeline_version": "1.0.2",
eta.node_version": "v9.10.0",
otals.mysql2.count": 2,
otals.mysql2.duration_ms": 13.291,
otals.mysql2.query.count": 2,
otals.mysql2.query.duration_ms": 13.291,
race.trace_id": "11ad83a2-ca8d-4918-9db2-27524456d9f7",
race.span_id": "4a3892ba-0936-46e1-8e17-31b887326027",
ame": "request",
ervice_name": "express",
uration_ms": 15.229326,
The following is a list of packages we've added instrumentation for. Some actually add context to events, while others are only instrumented to enable
context propagation (mostly the Promise
-like packages.)
Instrumented only for context propagation
Adds columns with prefix express.
| Name | Type |
| ——————— | ——————————————————– |
| express.userContext
| Array<string>\|Function<(request) => Object> |
express.userContext
If the value of this option is an array, it's assumed to be an array of string field names of req.user
. If a request has req.user
, the named fields are extracted and added to events with column names of express.user.$fieldName
.
For example:
If req.user
is an object { id: 1, username: "toshok" }
and your config settings include express: { userContext: ["username"] }
, the following will be included in the express event sent to honeycomb:
| request.user.username
|
| :———————- |
| toshok
|
If the value of this option is a function, it will be called on every request and passed the request as the sole argument. All key-values in the returned object will be added to the event. If the function returns a falsey value, no columns will be added. To replicate the above Array-based behavior, you could use the following config: express: { userContext: (req) => req.user && { username: req.user.username } }
This function isn't limited to using the request object, and can pull info from anywhere to enrich the data sent about the user.
Adds columns with prefix http.
Adds columns with prefix https.
Instrumented only for context propagation
Adds columns with prefix mysql2.
Adds columns with prefix react.
Instrumented only for context propagation
(if you'd like to see anything more here, please file an issue or :+1: one already filed!)
Use the DEBUG=honeycomb-beeline:*
environment variable to produce debug output.