Add readme and images

custom-instrumentation/distributed-tracing/README.md

@@ -0,0 +1,47 @@
+# Sample distributed tracing application 
+
+This example provides both a BullMQ producer and consumer with a redis instance. 
+
+The producer starts a transaction, adds headers into the transaction and then adds those headers as part of the job data to be added to the queue. The producer and the new relic agent will shutdown after 10 seconds. 
+
+The consmers start a transaction, processes the jobs from the queue and links the transaction from the producer by accepting its headers that were added as part of the job data. The producer and the new relic agent will shutdown after 60 seconds. 
+
+## Getting started
+**Note**: This application requires the use of Node.js v20+ and docker.
+
+ 1. Clone or fork this repository.
+
+ 2. Setup the redis container
+
+    ```sh
+    docker compose up -d 
+    ```
+
+ 3. Install dependencies and run application
+
+    ```sh
+    npm ci
+    cp env.sample .env
+    # Fill out `NEW_RELIC_LICENSE_KEY` in .env and save 
+    # Start the consumer
+    npm run start:consumer
+    # Start the producer in a different shell
+    npm run start:producer
+    ```
+***You can change the number of messages sent by editing the time in setTimeout in both the producer and the consumer.*** 
+
+## Exploring Telemetry
+After the producers sends a few messages and the consumers processes them, navigate to your application in `APM & Services`.  Select `Distributed tracing`. A transaction will be created and spans for the messages sent and processed. Since the consumer is running and handling message consumption, Distributed Tracing will link the two entities.
+
+![Producer distributed tracing](./images/producer-dt.png?raw=true "Producer distributed tracing")
+![Producer distributed trace](./images/producer-dt-trace.png?raw=true "Producer distributed trace")
+
+The producer service map shows two entities: the producer and consumer. 
+![Producer service map](./images/producer-service-map.png?raw=true "Producer service map")
+
+You will see a distributed trace and a service map for the consumer as well. 
+
+![Consumer distributed tracing](./images/consumer-dt.png?raw=true "Consumer distributed tracing")
+
+The consumer service map shows two entities (the producer and the consumer) and a redis instance. 
+![Consumer service map](./images/consumer-service-map.png?raw=true "Consumer service map")

custom-instrumentation/distributed-tracing/consumer.js

@@ -12,6 +12,7 @@ const connection = new IORedis({
   maxRetriesPerRequest: null
 })
 
+// since BullMQ is not auto instrumented by the newrelic node agent, we have to manually start a transaction
 return newrelic.startBackgroundTransaction('Message queue - consumer', function innerHandler() {
   const worker = new Worker(
     'jobQueue',
@@ -20,8 +21,13 @@ return newrelic.startBackgroundTransaction('Message queue - consumer', function
       console.log('Job data:', job.data)
       console.log('Job headers', job.data.headers)
 
+      // call newrelic.getTransaction to retrieve a handle on the current transaction
       const backgroundHandle = newrelic.getTransaction()
+
+      // link the transaction started in the producer by accepting its headers
       backgroundHandle.acceptDistributedTraceHeaders('Queue', job.data.headers)
+
+      // end the transaction
       backgroundHandle.end()
       return Promise.resolve()
     },
@@ -46,6 +52,6 @@ return newrelic.startBackgroundTransaction('Message queue - consumer', function
         // eslint-disable-next-line no-process-exit
         process.exit(0)
       })
-    }, 20000)
+    }, 60000)
   })
 })

custom-instrumentation/distributed-tracing/producer.js

@@ -14,18 +14,24 @@ const connection = new IORedis({
 
 const queue = new Queue('jobQueue', { connection })
 
+// since BullMQ is not auto instrumented by the newrelic node agent, we have to manually start a transaction.
 return newrelic.startBackgroundTransaction('Message queue - producer', function innerHandler() {
   console.log('Message queue started')
 
+  // call newrelic.getTransaction to retrieve a handle on the current transaction.
   const backgroundHandle = newrelic.getTransaction()
+
+  // insert the headers into the transaction
   const headers = { 'test-dt': 'test-newrelic' }
   backgroundHandle.insertDistributedTraceHeaders(headers)
 
+  // add jobs every 6 milliseconds with data containing the message and the headers
   setInterval(async () => {
     await queue.add('simpleJob', { message: 'This is a background job', headers })
     console.log('Job added to the queue')
   }, 600)
 
+  // end the transaction
   backgroundHandle.end()
 
   return new Promise((resolve) => {