chore: update readme with examples and installation instructions (#7)

README.md

@@ -1,35 +1,58 @@
 # Goodmetrics Nodejs
 
-example usage
+Nodejs metrics client to be used with either the goodmetrics protocol, or any open telemetry compliant protocol.
+Currently has a built in lightstep open telemetry client.
+
+This library is based off of the opensource [kotlin goodmetrics library](https://github.com/kvc0/goodmetrics_kotlin)
+
+## Installing
+```bash
+npm i goodmetrics-nodejs
+```
+
+example usages 
 ```javascript
 import {Dimension, MetricsSetups} from 'goodmetrics-nodejs';
 
-const delay = async (ms: number): Promise<void> => {
-  return await new Promise(resolve => {
-    setTimeout(() => {
-      resolve();
-    }, ms);
-  });
-};
-
 const main = async () => {
-  const metrics =
+    // metrics setup for recording metrics inside of a lambda
+  const lambdaMetrics =
     MetricsSetups.lightstepNativeOtlpButItSendsMetricsUponRecordingForLambda({
-      aggregationWidthMillis: 10 * 1000 * 1000,
+      aggregationWidthMillis: 10 * 1000,
       lightstepAccessToken: '<your lightstep api key>',
-      prescientDimensions: new Map<string, Dimension>(),
+      resourceDimensions: new Map<string, Dimension>(),
     });
 
-  await metrics.unaryMetricsFactory.record(
+  await lambdaMetrics.unaryMetricsFactory.record(
     {name: 'test'},
     async metrics => {
       console.info('inside metrics block');
       metrics.measure('runs', 1);
-      await delay(100);
+      // await some async task
       metrics.dimension('result', 'success');
     }
   );
+
+  // using goodmetrics
+  const goodmetrics = MetricsSetups.goodMetrics();
+  await goodmetrics.unaryMetricsFactory.record({name: 'unary'}, metrics => {
+    metrics.dimension('is_local', true);
+    metrics.measure('runs', 1);
+  });
+  await goodmetrics.preaggregatedMetricsFactory.record(
+    {name: 'preaggregated'},
+    metrics => {
+        metrics.measure('w00t', 1);
+    }
+  );
 };
 
 main().finally();
 ```
+
+## Protos
+- [open telemetry client protos](https://github.com/bruuuuuuuce/otlp-generated)
+- [goodmetrics client protos](https://github.com/bruuuuuuuce/goodmetrics-generated)
+
+## Goodmetrics
+More information about the goodmetrics protocol can be found [here](https://github.com/kvc0/goodmetrics)

src/goodmetrics/metricsSetups.ts

@@ -23,12 +23,34 @@ export interface ConfiguredMetrics {
 }
 
 interface LightstepNativeLambdaOtlpProps {
+  /**
+   * programmatic access token for the lightstep backend
+   * https://docs.lightstep.com/docs/create-and-manage-api-keys
+   */
   lightstepAccessToken: string;
-  prescientDimensions: Map<string, Dimension>;
+  /**
+   * Included resource dimensions on the OTLP resource. Ex. AWS_REGION, ACCOUNT_ID etc...
+   */
+  resourceDimensions: Map<string, Dimension>;
+  /**
+   * aggregated batch width in milliseconds
+   */
   aggregationWidthMillis: number;
+  /**
+   * defaults to `ingest.lightstep.com`, the default lightstep ingest url
+   */
   lightstepUrl?: string;
+  /**
+   * defaults to 443, the default lightstep port
+   */
   lightstepPort?: number;
+  /**
+   * defaults to SecurityMode.Tls, for use with https
+   */
   lightstepConnectionSecurityMode?: SecurityMode;
+  /**
+   * timeout for the requests to send metrics to lightsteps backend
+   */
   timeoutSeconds?: number;
   logError: (message: string, error: unknown) => void;
   onSendUnary?: (metrics: Metrics[]) => void;
@@ -84,10 +106,10 @@ interface GoodmetricsSetupProps {
 }
 
 export class MetricsSetups {
-  static goodMetrics(props: GoodmetricsSetupProps): ConfiguredMetrics {
-    const host = props.host ?? 'localhost';
-    const port = props.port ?? 9573;
-    const aggregationWidthMillis = props.aggregationWidthMillis ?? 10 * 1000;
+  static goodMetrics(props?: GoodmetricsSetupProps): ConfiguredMetrics {
+    const host = props?.host ?? 'localhost';
+    const port = props?.port ?? 9573;
+    const aggregationWidthMillis = props?.aggregationWidthMillis ?? 10 * 1000;
     const unaryFactory = this.configureGoodmetricsUnaryFactory({
       host: host,
       port: port,
@@ -146,6 +168,12 @@ export class MetricsSetups {
       preaggregatedMetricsFactory,
     };
   }
+
+  /**
+   * Configures a unary metric factory which will send and record metrics upon lambda
+   * completion
+   * @param props
+   */
   static lightstepNativeOtlpButItSendsMetricsUponRecordingForLambda(
     props: LightstepNativeLambdaOtlpProps
   ): MetricsFactory {
@@ -156,7 +184,7 @@ export class MetricsSetups {
       sillyOtlpHostname: props.lightstepUrl ?? 'ingest.lightstep.com',
       port: props.lightstepPort ?? 443,
       metricDimensions: new Map(),
-      resourceDimensions: new Map(),
+      resourceDimensions: props.resourceDimensions,
       interceptors: [
         new HeaderInterceptorProvider(headers).createHeadersInterceptor(),
       ],

src/index.ts

@@ -1,5 +1,5 @@
 import {SecurityMode} from './goodmetrics/downstream/openTelemetryClient';
-import {Dimension} from './goodmetrics/_Metrics';
+import {Dimension, Metrics} from './goodmetrics/_Metrics';
 import {MetricsSink} from './goodmetrics/pipeline/metricsSink';
 import {
   MetricsFactory,
@@ -15,4 +15,5 @@ export {
   TotaltimeType,
   TimestampAt,
   MetricsSetups,
+  Metrics,
 };

test/dev-driver.ts

@@ -1,5 +1,4 @@
-import {MetricsSetups} from '../src/goodmetrics/metricsSetups';
-import {Metrics} from '../src/goodmetrics/_Metrics';
+import {MetricsSetups, Metrics} from '../src';
 
 const delay = async (ms: number) => {
   return await new Promise<void>(resolve => {
@@ -12,7 +11,7 @@ const delay = async (ms: number) => {
 const main = async () => {
   const metrics = MetricsSetups.lightstepNativeOtlp({
     aggregationWidthMillis: 10 * 1000,
-    lightstepAccessToken: '',
+    lightstepAccessToken: process.env.LIGHTSTEP_ACCESS_TOKEN || '',
     logError(message: string, error: unknown): void {
       console.error(message, error);
     },
@@ -21,6 +20,18 @@ const main = async () => {
     },
   });
 
+  const goodmetrics = MetricsSetups.goodMetrics();
+  await goodmetrics.unaryMetricsFactory.record({name: 'unary'}, metrics => {
+    metrics.dimension('is_local', true);
+    metrics.measure('runs', 1);
+  });
+  await goodmetrics.preaggregatedMetricsFactory.record(
+    {name: 'preaggregated'},
+    metrics => {
+      metrics.measure('w00t', 1);
+    }
+  );
+
   await delay(8000);
   await metrics.unaryMetricsFactory.record(
     {