Improved docs

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
@@ -41,36 +41,6 @@ yarn dev:lib
 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

examples/express/README.md

@@ -27,7 +27,7 @@ Flag `--config.file` must point to the `prometheus.yml` configuration file
 3. Install the dependencies
 
 ```shell
-npm install
+yarn
 ```
 
 4. Build and run the application

examples/fastify/README.md

@@ -29,7 +29,7 @@ Flag `--config.file` must point to the `prometheus.yml` configuration file
 4. Install the dependencies
 
 ```shell
-npm install
+yarn
 ```
 
 5. Run the initial migration

examples/react-app/README.md

@@ -9,7 +9,7 @@ To see Autometrics in action:
 
 0. Clone this repo and make sure your terminal is inside `examples/react-app/`.
 
-1. Install `am`.
+1. Install [`am`](https://github.com/autometrics-dev/am).
 
 Mac users can use Homebrew:
 
@@ -60,7 +60,8 @@ look something like:
 >   ➜  Local:   http://localhost:4173/
 
 6. Now you have two URLs, one for the example app where you can generate
-traffic, which you should then be able to see in the Explorer UI.
+traffic, which you should then be able to see in the Explorer UI. It may take up
+to 30 seconds for data to show up in the UI.
 
 Assuming the Explorer endpoint is exactly as shown above, this will be the
 direct URL to the function that is generating traffic from the example app:

examples/react-app/src/App.tsx

@@ -6,13 +6,16 @@ import "./App.css";
 // In order for Prometheus to succesfully get your client-side app metrics, you
 // will need to push them to either a Prometheus-compatible aggregating push
 // gateway, or an OpenTelemetry Collector. Here, we choose to push to an Otel
-// Collector using OTLP over HTTP. (The `faas-experiment/` example uses a
+// Collector using OTLP over HTTP. (The `faas-experimental/` example uses a
 // Prometheus push gateway instead.)
 init({
   // A proxy configured in `vite.config.ts` forwards the `/metrics` endpoint
   // to the Otel Collector.
-  url: "/metrics",
-  pushInterval: 0,
+  url: "https://wercker.fmp.fiberplane.dev/otel/http/v1/metrics",
+  // Uncomment the next line to push "eagerly" instead of in batches. Eager
+  // pushing may generate more traffic, but reduces chances of missing metrics
+  // when the user closes their tab.
+  //pushInterval: 0,
   buildInfo: {
     version: import.meta.env.VITE_AUTOMETRICS_VERSION,
     commit: import.meta.env.VITE_AUTOMETRICS_COMMIT,

packages/exporter-otlp-http/src/index.ts

@@ -25,6 +25,8 @@ export type InitOptions = {
    *
    * Set to `0` to push eagerly without batching metrics. This is mainly useful
    * for edge functions and some client-side scenarios.
+   *
+   * Note the push interval may not be smaller than the `timeout`.
    */
   pushInterval?: number;
 
@@ -35,6 +37,8 @@ export type InitOptions = {
 
   /**
    * The timeout for pushing metrics, in milliseconds (default: `1000ms`).
+   *
+   * Note the timeout may not be larger than the `pushInterval`.
    */
   timeout?: number;