@tryghost/metrics 3.4.1 → 3.4.2

package/README.md

@@ -14,6 +14,53 @@ Ghost metrics facade for collecting and emitting operational metrics across serv
 
 ## Usage
 
+The default export is a pre-configured `GhostMetrics` instance, built from the
+`loggingrc` file at the process root if one exists. The `GhostMetrics` class is
+attached to it for creating additional instances.
+
+```js
+const metrics = require('@tryghost/metrics');
+
+await metrics.metric('memory-usage', process.memoryUsage().heapUsed);
+
+const custom = new metrics.GhostMetrics({
+    domain: 'my-service',
+    metrics: { transports: ['stdout'] },
+});
+```
+
+### Types
+
+Types ship with the package. `GhostMetrics` is exported as both a value (the
+class) and a type (an instance of it), alongside the options and shipper types:
+
+```ts
+import metrics, { GhostMetrics } from '@tryghost/metrics';
+import type {
+    GhostMetrics as GhostMetricsInstance,
+    GhostMetricsOptions,
+    MetricsOptions,
+    ElasticsearchOptions,
+    MetricShipper,
+} from '@tryghost/metrics';
+
+const options: GhostMetricsOptions = { domain: 'my-service' };
+const custom: GhostMetricsInstance = new GhostMetrics(options);
+
+function ship(instance: GhostMetricsInstance, name: string, value: unknown) {
+    return instance.metric(name, value);
+}
+```
+
+In a CommonJS file the whole surface is reachable through a single import:
+
+```ts
+import metrics = require('@tryghost/metrics');
+
+const custom: metrics.GhostMetrics = new metrics.GhostMetrics({ domain: 'my-service' });
+const options: metrics.GhostMetricsOptions = {};
+```
+
 ## Develop
 
 This is a mono repository, managed with [Nx](https://nx.dev).

package/lib/metrics.d.ts

@@ -1,18 +1,23 @@
-import GhostMetrics = require('./GhostMetrics');
+import GhostMetricsClass = require('./GhostMetrics');
 
 /**
  * A pre-configured `GhostMetrics` instance (built from `loggingrc` if present),
  * with the `GhostMetrics` class attached for creating additional instances.
  */
-declare const metrics: GhostMetrics & {
-    GhostMetrics: typeof GhostMetrics;
+declare const metrics: GhostMetricsClass & {
+    GhostMetrics: typeof GhostMetricsClass;
 };
 
 declare namespace metrics {
-    export type ElasticsearchOptions = GhostMetrics.ElasticsearchOptions;
-    export type MetricsOptions = GhostMetrics.MetricsOptions;
-    export type GhostMetricsOptions = GhostMetrics.GhostMetricsOptions;
-    export type MetricShipper = GhostMetrics.MetricShipper;
+    /**
+     * Instance type of the `GhostMetrics` class, so consumers can annotate
+     * values with `GhostMetrics` without reaching for `InstanceType<>`.
+     */
+    export type GhostMetrics = GhostMetricsClass;
+    export type ElasticsearchOptions = GhostMetricsClass.ElasticsearchOptions;
+    export type MetricsOptions = GhostMetricsClass.MetricsOptions;
+    export type GhostMetricsOptions = GhostMetricsClass.GhostMetricsOptions;
+    export type MetricShipper = GhostMetricsClass.MetricShipper;
 }
 
 export = metrics;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/metrics",
-  "version": "3.4.1",
+  "version": "3.4.2",
   "license": "MIT",
   "author": "Ghost Foundation",
   "repository": {
@@ -20,13 +20,13 @@
   },
   "dependencies": {
     "json-stringify-safe": "5.0.1",
-    "@tryghost/elasticsearch": "5.4.4",
-    "@tryghost/pretty-stream": "2.3.7",
-    "@tryghost/root-utils": "2.3.7"
+    "@tryghost/elasticsearch": "^5.4.5",
+    "@tryghost/pretty-stream": "^2.3.8",
+    "@tryghost/root-utils": "^2.3.8"
   },
   "devDependencies": {
     "rewire": "9.0.1",
-    "sinon": "22.0.0"
+    "sinon": "22.1.0"
   },
   "scripts": {
     "dev": "echo \"Implement me!\"",