From cf985d9695d5d20d852e9dc0462b50d31ac7aaf4 Mon Sep 17 00:00:00 2001 From: Michal Raczka Date: Wed, 26 Sep 2018 14:03:50 +0200 Subject: [PATCH 1/3] Introduce DATADOG_HOST env var --- CHANGELOG.md | 3 +++ package.json | 2 +- src/infra/instrumentation/instrumentation-agent.js | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c30079..20f9ba6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +# 0.13.17 +* introduce a `DATADOG_HOST` environment variable to take precedence generic `HOST` env var + # 0.13.16 * Explicitly handle too large kraken notification payloads * Adds devMode utility diff --git a/package.json b/package.json index 96a9be6..d0731ea 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hull", - "version": "0.13.16", + "version": "0.13.17", "description": "A Node.js client for hull.io", "main": "lib", "repository": { diff --git a/src/infra/instrumentation/instrumentation-agent.js b/src/infra/instrumentation/instrumentation-agent.js index 98bf7ab..86a848d 100644 --- a/src/infra/instrumentation/instrumentation-agent.js +++ b/src/infra/instrumentation/instrumentation-agent.js @@ -42,7 +42,7 @@ class InstrumentationAgent { if (process.env.DATADOG_API_KEY) { this.metrics = metrics; metrics.init({ - host: process.env.HOST, + host: process.env.DATADOG_HOST || process.env.HOST, }); dogapi.initialize({ api_key: process.env.DATADOG_API_KEY }); this.dogapi = dogapi; From d56d6dcbf9ee991318088c3ee467571c488cb5f7 Mon Sep 17 00:00:00 2001 From: Michal Raczka Date: Thu, 27 Sep 2018 23:32:35 +0200 Subject: [PATCH 2/3] Require process.env.DATADOG_HOST --- API.md | 88 +++++++++---------- .../instrumentation/instrumentation-agent.js | 5 +- 2 files changed, 48 insertions(+), 45 deletions(-) diff --git a/API.md b/API.md index 47a672c..e80e358 100644 --- a/API.md +++ b/API.md @@ -2,7 +2,7 @@ ## HullConnector -**Parameters** +### Parameters - `HullClient` **HullClient** - `options` **[Object][1]** (optional, default `{}`) @@ -29,7 +29,7 @@ This method applies all features of `Hull.Connector` to the provided application - initiating the wole [Context Object][5] - handling the `hullToken` parameter in a default way -**Parameters** +#### Parameters - `app` **express** expressjs application @@ -39,7 +39,7 @@ Returns **express** expressjs application This is a supplement method which calls `app.listen` internally and also terminates instrumentation of the application calls. -**Parameters** +#### Parameters - `app` **express** expressjs application @@ -56,7 +56,7 @@ General utilities This is an error related to wrong connector configuration. It's a transient error, but it makes sense to retry the payload only after the connector settings update. -**Parameters** +#### Parameters - `message` **[string][2]** - `extra` **[Object][1]** @@ -69,13 +69,13 @@ This is an error which should be handled by the connector implementation itself. Rejecting or throwing this error without try/catch block will be treated as unhandled error. -**Parameters** +#### Parameters - `message` **[string][2]** - `action` **[string][2]** - `payload` **any** -**Examples** +#### Examples ```javascript function validationFunction() { @@ -91,7 +91,7 @@ This is a subclass of TransientError. It have similar nature but it's very common during connector operations so it's treated in a separate class. Usually connector is able to tell more about when exactly the rate limit error will be gone to optimize retry strategy. -**Parameters** +#### Parameters - `message` **[string][2]** - `extra` **[Object][1]** @@ -104,7 +104,7 @@ This error means that 3rd party API resources is out of sync comparing to Hull o For example customer by accident removed a resource which we use to express segment information (for example user tags, user sub lists etc.) So this is a TransientError which could be retried after forcing "reconciliation" operation (which should recreate missing resource) -**Parameters** +#### Parameters - `message` **[string][2]** - `extra` **[Object][1]** @@ -117,7 +117,7 @@ This is a transient error related to either connectivity issues or temporary 3rd When using `superagentErrorPlugin` it's returned by some errors out-of-the-box. -**Parameters** +#### Parameters - `message` **[string][2]** - `extra` **[Object][1]** @@ -135,7 +135,7 @@ This is a set of additional helper functions being exposed at `req.hull.helpers` Helper function to handle JSON extract sent to batch endpoint -**Parameters** +##### Parameters - `ctx` **[Object][1]** Hull request context - `options` **[Object][1]** @@ -151,7 +151,7 @@ Returns **[Promise][7]** This is a method to request an extract of user base to be sent back to the Connector to a selected `path` which should be handled by `notifHandler`. -**Parameters** +##### Parameters - `ctx` **[Object][1]** Hull request context - `options` **[Object][1]** (optional, default `{}`) @@ -161,7 +161,7 @@ This is a method to request an extract of user base to be sent back to the Conne - `options.fields` **[Object][1]** (optional, default `[]`) - `options.additionalQuery` **[Object][1]** (optional, default `{}`) -**Examples** +##### Examples ```javascript req.hull.helpers.requestExtract({ segment = null, path, fields = [], additionalQuery = {} }); @@ -174,12 +174,12 @@ Returns **[Promise][7]** Allows to update selected settings of the ship `private_settings` object. This is a wrapper over `hullClient.utils.settings.update()` call. On top of that it makes sure that the current context ship object is updated, and the ship cache is refreshed. It will emit `ship:update` notify event. -**Parameters** +##### Parameters - `ctx` **[Object][1]** The Context Object - `newSettings` **[Object][1]** settings to update -**Examples** +##### Examples ```javascript req.hull.helpers.updateSettings({ newSettings }); @@ -199,7 +199,7 @@ If you want to customize cache behavior (for example ttl, storage etc.) please @ Hull client calls which fetch ship settings could be wrapped with this method to cache the results -**Parameters** +##### Parameters - `key` **[string][2]** - `cb` **[Function][6]** callback which Promised result would be cached @@ -211,7 +211,7 @@ Returns **[Promise][7]** Saves ship data to the cache -**Parameters** +##### Parameters - `key` **[string][2]** - `value` **mixed** @@ -223,7 +223,7 @@ Returns **[Promise][7]** Returns cached information -**Parameters** +##### Parameters - `key` **[string][2]** @@ -234,7 +234,7 @@ Returns **[Promise][7]** Clears the ship cache. Since Redis stores doesn't return promise for this method, it passes a callback to get a Promise -**Parameters** +##### Parameters - `key` **[string][2]** @@ -246,7 +246,7 @@ Metric agent available as `req.hull.metric` object. This class is being initiated by InstrumentationAgent. If you want to change or override metrics behavior please @see Infra.InstrumentationAgent -**Examples** +#### Examples ```javascript req.hull.metric.value("metricName", metricValue = 1); @@ -258,7 +258,7 @@ req.hull.metric.event("eventName", { text = "", properties = {} }); Sets metric value for gauge metric -**Parameters** +##### Parameters - `metric` **[string][2]** metric name - `value` **[number][3]** metric value (optional, default `1`) @@ -270,7 +270,7 @@ Returns **mixed** Increments value of selected metric -**Parameters** +##### Parameters - `metric` **[string][2]** metric metric name - `value` **[number][3]** value which we should increment metric by (optional, default `1`) @@ -280,7 +280,7 @@ Returns **mixed** #### event -**Parameters** +##### Parameters - `options` **[Object][1]** - `options.title` **[string][2]** @@ -291,7 +291,7 @@ Returns **mixed** ### enqueue -**Parameters** +#### Parameters - `queueAdapter` **[Object][1]** adapter to run - when using this function in Context this param is bound - `ctx` **[Context][10]** Hull Context Object - when using this function in Context this param is bound @@ -303,7 +303,7 @@ Returns **mixed** - `options.queueName` **[string][2]?** when you start worker with a different queue name, you can explicitly set it here to queue specific jobs to that queue - `options.priority` **([number][3] \| [string][2])?** you can use this param to specify priority of job -**Examples** +#### Examples ```javascript // app is Hull.Connector wrapped expressjs app @@ -326,7 +326,7 @@ Returns **[Promise][7]** which is resolved when job is successfully enqueued Production ready connectors need some infrastructure modules to support their operation, allow instrumentation, queueing and caching. The [Hull.Connector][11] comes with default settings, but also allows to initiate them and set a custom configuration: -**Examples** +### Examples ```javascript const instrumentation = new Instrumentation(); @@ -363,11 +363,11 @@ ctx.cache.wrap('object_name', () => { > > **IMPORTANT** internal caching of `ctx.ship` object is refreshed on `ship:update` notifications, if the connector doesn't subscribe for notification at all the cache won't be refreshed automatically. In such case disable caching, set short TTL or add `notifHandler` -**Parameters** +#### Parameters - `options` **[Object][1]** passed to node-cache-manager (optional, default `{}`) -**Examples** +#### Examples ```javascript const redisStore = require("cache-manager-redis"); @@ -391,11 +391,11 @@ It automatically sends data to DataDog, Sentry and Newrelic if appropriate ENV V It also exposes the `contextMiddleware` which adds `req.hull.metric` agent to add custom metrics to the ship. Right now it doesn't take any custom options, but it's showed here for the sake of completeness. -**Parameters** +#### Parameters - `options` (optional, default `{}`) -**Examples** +#### Examples ```javascript const { Instrumentation } = require("hull/lib/infra"); @@ -434,11 +434,11 @@ connector.worker({ connector.startWorker(); ``` -**Parameters** +#### Parameters - `adapter` **[Object][1]** -**Examples** +#### Examples ````javascript ```javascript @@ -461,7 +461,7 @@ const connector = new Hull.Connector({ queue }); This middleware standardizes the instantiation of a [Hull Client][17] in the context of authorized HTTP request. It also fetches the entire ship's configuration. -**Parameters** +### Parameters - `HullClient` **HullClient** Hull Client - the version exposed by this library comes with HullClient argument bound - `options` **[Object][1]** @@ -486,7 +486,7 @@ NotifHandler is a packaged solution to receive User and Segment Notifications fr } ``` -**Parameters** +#### Parameters - `params` **[Object][1]** - `params.handlers` **[Object][1]** @@ -498,7 +498,7 @@ NotifHandler is a packaged solution to receive User and Segment Notifications fr - `params.options.groupTraits` **[boolean][4]** (optional, default `false`) - `params.userHandlerOptions` **[Object][1]?** deprecated -**Examples** +#### Examples ```javascript import { notifHandler } from "hull/lib/utils"; @@ -558,7 +558,7 @@ To make it working in Hull dashboard set following line in **manifest.json** fil For example of the notifications payload [see details][19] -**Parameters** +#### Parameters - `options` **[Object][1]** - `options.name` **[string][2]** The name displayed to the User in the various screens. @@ -571,7 +571,7 @@ For example of the notifications payload [see details][19] - `options.views` **[Object][1]** Required, A hash of view files for the different screens: login, home, failure, success - `options.options` **[Object][1]** Hash passed to Passport to configure the OAuth Strategy. (See [Passport OAuth Configuration][20]) -**Examples** +#### Examples ```javascript const { oAuthHandler } = require("hull/lib/utils"); @@ -653,7 +653,7 @@ Returns **[Function][6]** OAuth handler to use with expressjs When performing operations on notification you can set FlowControl settings using `ctx.smartNotifierResponse` helper. -**Parameters** +#### Parameters - `params` **[Object][1]** - `params.handlers` **[Object][1]** @@ -664,7 +664,7 @@ When performing operations on notification you can set FlowControl settings usin - `params.options.groupTraits` **[boolean][4]** (optional, default `false`) - `params.userHandlerOptions` **[Object][1]?** deprecated -**Examples** +#### Examples ```javascript const { smartNotifierHandler } = require("hull/lib/utils"); @@ -722,13 +722,13 @@ In case of any other request the plugin applies simple error handling strategy: every non 2xx or 3xx response is treated as an error and the promise will be rejected. Every connector ServiceClient should apply it's own error handling strategy by overriding `ok` handler. -**Parameters** +#### Parameters - `options` **[Object][1]** (optional, default `{}`) - `options.retries` **[Number][3]?** Number of retries - `options.timeout` **[Number][3]?** Timeout for request -**Examples** +#### Examples ```javascript superagent.get("http://test/test") @@ -763,13 +763,13 @@ This plugin takes `client.logger` and `metric` params from the `Context Object` The plugin also issue a metric with the same name `ship.service_api.request`. -**Parameters** +#### Parameters - `options` **[Object][1]** - `options.logger` **[Object][1]** Logger from HullClient - `options.metric` **[Object][1]** Metric from Hull.Connector -**Examples** +#### Examples ````javascript const superagent = require('superagent'); @@ -824,11 +824,11 @@ Returns **[Function][6]** function to use as superagent plugin This plugin allows to pass generic url with variables - this allows better instrumentation and logging on the same REST API endpoint when resource ids varies. -**Parameters** +#### Parameters - `defaults` **[Object][1]** default template variable -**Examples** +#### Examples ```javascript const superagent = require('superagent'); diff --git a/src/infra/instrumentation/instrumentation-agent.js b/src/infra/instrumentation/instrumentation-agent.js index 86a848d..fa75d5a 100644 --- a/src/infra/instrumentation/instrumentation-agent.js +++ b/src/infra/instrumentation/instrumentation-agent.js @@ -40,9 +40,12 @@ class InstrumentationAgent { } if (process.env.DATADOG_API_KEY) { + if (!process.env.DATADOG_HOST) { + throw new Error("When using Datadog integration you must provide `DATADOG_HOST` env var"); + } this.metrics = metrics; metrics.init({ - host: process.env.DATADOG_HOST || process.env.HOST, + host: process.env.DATADOG_HOST, }); dogapi.initialize({ api_key: process.env.DATADOG_API_KEY }); this.dogapi = dogapi; From 5c7ccaf387ec939e47fd2a0c87e694b53695ff11 Mon Sep 17 00:00:00 2001 From: Michal Raczka Date: Fri, 28 Sep 2018 10:08:56 +0200 Subject: [PATCH 3/3] Update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 20f9ba6..226cbf2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,5 @@ # 0.13.17 -* introduce a `DATADOG_HOST` environment variable to take precedence generic `HOST` env var +* introduce a `DATADOG_HOST` environment variable which is required if Datadog integration is enabled # 0.13.16 * Explicitly handle too large kraken notification payloads