Exporter packages

.github/workflows/ci.yml

@@ -2,28 +2,22 @@ name: CI
 on:
   push:
     branches: ["*"]
-  pull_request:
-    branches: [main]
 
 jobs:
   test:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: rome/[email protected]
-        with:
-          version: latest
-
       - uses: actions/checkout@v3
 
       - name: Setup the project
-        run: npm ci
-
-      - name: Install rome cli tools
-        run: npm install @rometools/cli-linux-x64
+        run: yarn
 
       - name: Run linter and format checker
-        run: npm run lint
+        run: yarn lint
+
+      - name: Create a build
+        run: yarn build
 
       - name: Run unit tests
-        run: npm run test
+        run: yarn test

.github/workflows/publish_lib_to_npm.yml

@@ -1,4 +1,4 @@
-name: Publish lib/ (and convenience package autometrics/) packages to NPMJS
+name: Publish main @autometrics/autometrics and the exporters to NPM
 on:
   push:
     tags:
@@ -8,24 +8,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-
-      - uses: rome/[email protected]
-        with:
-          version: latest
-
       - uses: actions/checkout@v3
 
       - name: Setup the project
-        run: npm ci
-
-      - name: Install rome cli tools
-        run: npm install @rometools/cli-linux-x64
+        run: yarn
 
       - name: Run linter and format checker
-        run: npm run lint
+        run: yarn lint
 
       - name: Run unit tests
-        run: npm run test
+        run: yarn test
 
   publish:
     runs-on: ubuntu-latest
@@ -39,9 +31,19 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
           scope: "@autometrics"
 
-      - run: npm ci
-
-      - run: npm run build --workspace=@autometrics/autometrics --workspace=autometrics
-      - run: npm run release --workspace=@autometrics/autometrics --workspace=autometrics 
+      - run: yarn
+
+      - run: |
+          yarn build \
+            --workspace=@autometrics/autometrics \
+            --workspace=@autometrics/exporter-otlp-http \
+            --workspace=@autometrics/exporter-prometheus \
+            --workspace=@autometrics/exporter-prometheus-push-gateway
+      - run: |
+          yarn release \
+            --workspace=@autometrics/autometrics \
+            --workspace=@autometrics/exporter-otlp-http \
+            --workspace=@autometrics/exporter-prometheus \
+            --workspace=@autometrics/exporter-prometheus-push-gateway
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/publish_parcel_plugin_to_npm.yml

@@ -1,4 +1,4 @@
-name: Publish Parcel transformer plugin package to NPMJS
+name: Publish Parcel transformer plugin package to NPM
 on:
   push:
     tags:
@@ -8,24 +8,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-
-      - uses: rome/[email protected]
-        with:
-          version: latest
-
       - uses: actions/checkout@v3
 
       - name: Setup the project
-        run: npm ci
-
-      - name: Install rome cli tools
-        run: npm install @rometools/cli-linux-x64
+        run: yarn
 
       - name: Run linter and format checker
-        run: npm run lint
+        run: yarn lint
 
       - name: Run unit tests
-        run: npm run test
+        run: yarn test
 
   publish:
     runs-on: ubuntu-latest
@@ -39,10 +31,11 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
           scope: "@autometrics"
 
-      - run: npm ci
+      - run: yarn
+
+      - run: yarn build --workspace=@autometrics/parcel-transformer-autometrics
 
-      - run: npm run build --workspace=@autometrics/parcel-transformer-autometrics
-      - run: npm run release --workspace=@autometrics/parcel-transformer-autometrics
+      - run: yarn release --workspace=@autometrics/parcel-transformer-autometrics
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

.github/workflows/publish_typescript_plugin_to_npm.yml

@@ -1,4 +1,4 @@
-name: Publish TypeScript plugin package to NPMJS
+name: Publish TypeScript plugin package to NPM
 on:
   push:
     tags:
@@ -8,21 +8,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-
-      - uses: rome/[email protected]
-        with:
-          version: latest
-
       - uses: actions/checkout@v3
 
       - name: Setup the project
-        run: npm ci
-
-      - name: Install rome cli tools
-        run: npm install @rometools/cli-linux-x64
+        run: yarn
 
       - name: Run linter and format checker
-        run: npm run lint
+        run: yarn lint
 
   publish:
     runs-on: ubuntu-latest
@@ -36,10 +28,11 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
           scope: "@autometrics"
 
-      - run: npm ci
+      - run: yarn
+
+      - run: yarn build --workspace=@autometrics/typescript-plugin
 
-      - run: npm run build --workspace=@autometrics/typescript-plugin
-      - run: npm run release --workspace=@autometrics/typescript-plugin
+      - run: yarn release --workspace=@autometrics/typescript-plugin
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

.gitignore

@@ -25,6 +25,15 @@ yarn-debug.log*
 yarn-error.log*
 lerna-debug.log*
 
+# Yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
 # OS
 .DS_Store
 

.yarnrc.yml

@@ -0,0 +1,7 @@
+nodeLinker: node-modules
+
+plugins:
+  - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
+    spec: "@yarnpkg/plugin-workspace-tools"
+
+yarnPath: .yarn/releases/yarn-3.6.3.cjs

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [unreleased]
 
+- **Breaking change:** Split the exporters into separate packages. Users will
+  need to explicitly choose an exporter and call its `init()` function.
 - (_experimental_) Push metrics to gateway "eagerly" when pushInterval is set to 0
 - Log error when fetch is not defined in push context
 

CONTRIBUTING.md

@@ -2,12 +2,12 @@
 
 ## Development workflow
 
-The project uses as `npm` as the package manager.
+The project uses `yarn` as the package manager.
 
 ```shell
 git clone [email protected]:autometrics-dev/autometrics-ts.git
 cd autometrics-ts
-npm install
+yarn
 ```
 
 ### Overview
@@ -31,46 +31,16 @@ into the generated query templates.
 
 ```shell
 # in project root
-npm run dev:lib
+yarn dev:lib
 ```
 
 ##### TypeScript plugin
 
 ```shell
 # in project root
-npm run dev:plugin
+yarn dev:plugin
 ```
 
-#### Use examples
-
-Use the examples in `examples/` to test your changes. You will need to reinstall
-autometrics packages to use the local development ones to see the changes
-reflected.
-
-Example with the `express` app:
-
-1. Remove the official npm released autometrics packages
-
-```shell
-npm uninstall @autometrics/autometrics @autometrics/typescript-plugin
-```
-
-2. Install local versions of autometrics
-
-```shell
-# from examples/express
-npm install ../../packages/autometrics/
-npm install -D ../../packages/typescript-plugin/
-```
-
-Now every time you will save and rebuild any of the packages they will update in
-your example repo automatically (you won't need to re-run `npm install`)
-
-Open the `express` app with your editor, e.g.: VSCode - `code examples/express/`
-
-This is now your "lab" environment for testing out how the library or the plugin
-work and feel.
-
 #### Debugging TypeScript plugin
 
 0. Run `Launch VSCode` and `Attach VSCode` in debugger

README.md

@@ -31,7 +31,7 @@ Autometrics provides a wrapper function and decorator to instrument functions, c
 ## Example
 
 ```typescript
-import { autometrics } from "autometrics";
+import { autometrics } from "@autometrics/autometrics";
 
 const createUserWithMetrics = autometrics(async function createUser(payload: User) {
   // ...
@@ -47,17 +47,17 @@ createUserWithMetrics();
 1. **Install the library**
 
 ```bash
-npm install --save autometrics
+npm install @autometrics/autometrics
 # or
-yarn add --save autometrics
+yarn add @autometrics/autometrics
 # or
-pnpm add --save autometrics
+pnpm add @autometrics/autometrics
 ```
 
 2. **Instrument your code using the `autometrics` wrapper or `Autometrics` decorator**
 
 ```typescript
-import { autometrics } from "autometrics";
+import { autometrics } from "@autometrics/autometrics";
 
 const createUserWithMetrics = autometrics(async function createUser(payload: User) {
   // ...
@@ -67,7 +67,7 @@ createUserWithMetrics();
 ```
 
 ```typescript
-import { Autometrics } from "autometrics";
+import { Autometrics } from "@autometrics/autometrics";
 
 class User {
   @Autometrics()
@@ -131,6 +131,72 @@ Add the language service plugin to the `tsconfig.json` file:
 
 ## [API Reference](./packages/lib/reference/README.md)
 
+## Recipes
+
+Below are two recipes for using Autometrics in a server-side setup and a
+client-side setup. If you would like to see examples with specific frameworks,
+please have a look at the [examples/](examples/) directory.
+
+### Server-side example with Prometheus
+
+#### Installation
+
+```shell
+npm install @autometrics/autometrics @autometrics/exporter-prometheus
+# or
+yarn add @autometrics/autometrics @autometrics/exporter-prometheus
+# or
+pnpm add @autometrics/autometrics @autometrics/exporter-prometheus
+```
+
+#### Usage
+
+1. Anywhere in your source code:
+
+```typescript
+import { autometrics } from "@autometrics/autometrics";
+import { init } from "@autometrics/exporter-prometheus";
+
+init(); // starts the webserver with the `/metrics` endpoint on port 4964
+
+async function createUserRaw(payload: User) {
+  // ...
+}
+
+const createUser = autometrics(createUserRaw);
+   // ^ instrumented function
+```
+
+### Recipe: Client-side example with the OpenTelemetry Collector
+
+#### Installation
+
+```shell
+npm install @autometrics/autometrics @autometrics/exporter-otlp-http
+# or
+yarn add @autometrics/autometrics @autometrics/exporter-otlp-http
+# or
+pnpm add @autometrics/autometrics @autometrics/exporter-otlp-http
+```
+
+#### Usage
+
+1. Anywhere in your source code:
+
+```typescript
+import { autometrics } from "@autometrics/autometrics";
+import { init } from "@autometrics/exporter-otlp-http";
+
+init({ url: "https://<your-otel-collector>" });
+
+async function createUserRaw(payload: User) {
+  // ...
+}
+
+const createUser = autometrics(createUserRaw);
+   // ^ instrumented function
+```
+
 ## Contributing
 
 Issues, feature suggestions, and pull requests are very welcome!