Make README example less pseudo-y

README.md

@@ -29,35 +29,110 @@ It must be configured before defining routes and other plugins in order to cover
   - `onResponse`
   - `onError`
 - Instruments automatically custom 404 Not Found handler
+- TODO: Clarify server shutdown/cleanup around otel metrics/traces
 
-Example:
+## Example
 
 ```js
-// ... in your OTEL setup
-const FastifyOtelInstrumentation = require('@fastify/otel');
+// otel.js
+// Sets up metrics, tracing, HTTP & Node runtime instrumentation, and host metrics.
+// Uses ConsoleSpanExporter for local debugging of spans.
+const { NodeSDK } = require('@opentelemetry/sdk-node')
+const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node')
+const { SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base')
+const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus')
+const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http')
+const { RuntimeNodeInstrumentation } = require('@opentelemetry/instrumentation-runtime-node')
+const { HostMetrics } = require('@opentelemetry/host-metrics')
+const { FastifyOtelInstrumentation } = require('@fastify/otel')
+const { metrics, trace } = require('@opentelemetry/api')
+const { resourceFromAttributes } = require('@opentelemetry/resources')
+const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions')
+
+// Console exporter for development-time span inspection
+// We could use '@opentelemetry/exporter-trace-otlp-http' instead
+const traceExporter = new ConsoleSpanExporter()
+const spanProcessor = new SimpleSpanProcessor(traceExporter)
+
+const prometheusExporter = new PrometheusExporter({ port: 9091 })
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service-name',
+  }),
+  spanProcessor,
+  metricReader: prometheusExporter,
+  instrumentations: [
+    new HttpInstrumentation(),
+    new RuntimeNodeInstrumentation(),
+  ],
+})
+
+await sdk.start()
 
-// If serverName is not provided, it will fallback to OTEL_SERVICE_NAME
-// as per https://opentelemetry.io/docs/languages/sdk-configuration/general/.
-const fastifyOtelInstrumentation = new FastifyOtelInstrumentation({ servername: '<yourCustomApplicationName>' });
-fastifyOtelInstrumentation.setTracerProvider(provider)
+const fastifyOtelInstrumentation = new FastifyOtelInstrumentation({
+  registerOnInitialization: true,
+})
+fastifyOtelInstrumentation.setTracerProvider(trace.getTracerProvider())
 
-module.exports = { fastifyOtelInstrumentation }
+new HostMetrics({ meterProvider: metrics.getMeterProvider() }).start()
 
-// ... in your Fastify definition
-const { fastifyOtelInstrumentation } = require('./otel.js');
-const Fastify = require('fastify');
+module.exports = { sdk, fastifyOtelInstrumentation }
+```
 
-const app = fastify();
+If `registerOnInitialization=true`, use a loader to load your otel.js before everything else.
+
+[Fastify-cli](https://github.com/fastify/fastify-cli):
+
+- `fastify start --import otel.js` for esm
+- `fastify start --require otel.js` for cjs
+
+Node.js:
+
+- `node --import ./otel.js ./app.js` for esm
+- `node --require ./otel.js ./app.js` for cjs
+
+```js
+// app.js
+import Fastify from 'fastify';
+
+// Because we used a loader flag and registerOnInitialization=true
+// All routes will automatically be insturmented
+const app = await Fastify();
+
+app.get('/', async () => 'hello world');
+
+app.get(
+  '/healthcheck',
+  { config: { otel: false } },       // skip tracing/metrics for this route
+  async () => 'Up!'
+);
+
+// example of encapsulated context with its own instrumentation
+app.register(async (instance) => {
+  // will inherit global FastifyOtelInstrumentation because we registered with
+  // registerOnInitialization
+  instance.get('/', async () => 'nested hello world');
+}, { prefix: '/nested' });
+
+await app.listen({ port: 3000 });
+console.log('⚡ Fastify listening on http://localhost:3000');
+````
+
+### Manual plugin registration
+
+If `registerOnInitialization=false`, you must register the fastify plugin before defining any routes.
+
+```js
+import Fastify from 'fastify';
+import { fastifyOtelInstrumentation } from './otel.js';
+
+const app = await Fastify();
 // It is necessary to await for its register as it requires to be able
 // to intercept all route definitions
 await app.register(fastifyOtelInstrumentation.plugin());
 
-// automatically all your routes will be instrumented
-app.get('/', () => 'hello world')
-// as well as your instance level hooks.
-app.addHook('onError', () => /* do something */)
-// Manually skip telemetry for a specific route
-app.get('/healthcheck', { config: { otel: false } }, () => 'Up!')
+app.get('/', async () => 'hello world');
 
 // you can also scope your instrumentation to only be enabled on a sub context
 // of your application
@@ -69,23 +144,7 @@ app.register((instance, opts, done) => {
 
     done()
 }, { prefix: '/nested' })
-```
-
-### Automatic plugin registration
-
-The plugin can be automatically registered with `registerOnInitialization` option set to `true`.
-In this case, it is necessary to await fastify instance.
-
-```js
-// ... in your OTEL setup
-const fastifyOtelInstrumentation = new FastifyOtelInstrumentation({
-  registerOnInitialization: true,
-});
-
-// ... in your Fastify definition
-const Fastify = require('fastify');
-const app = await fastify();
-```
+````
 
 > **Notes**:
 >