docs(evp-proxy): explain receiver discovery

Author: leoromanovsky

packages/dd-trace/src/evp_proxy/discovery.js

@@ -1,9 +1,48 @@
 'use strict'
 
 const { fetchAgentInfo } = require('../agent/info')
+const log = require('../log')
 
 const TRAILING_SLASHES = /\/+$/
 
+/**
+ * Receiver discovery contract
+ *
+ * The tracer sends `GET /info` to its configured local Agent URL. An
+ * Agent-compatible trace receiver produces the response. The tracer does not.
+ *
+ * The full Agent and serverless-init embed the same trace receiver. A future
+ * in-process receiver can expose the same contract. Callers can therefore
+ * select capabilities without detecting the receiver implementation.
+ *
+ * For EVP discovery, `endpoints` advertises registered proxy paths.
+ * `evp_proxy_allowed_headers` advertises headers that the proxy forwards to
+ * intake. It does not include routing headers that the proxy consumes, such as
+ * `X-Datadog-EVP-Subdomain`.
+ *
+ * An advertised route is not a health check. The receiver can register an EVP
+ * route while configuration disables its handler. The request then returns
+ * `405`. The `/info` version also identifies the embedded Agent code, not a
+ * serverless-init image or deployment type.
+ *
+ * This module only discovers a candidate route. A missing or unresponsive
+ * `/info` endpoint returns an error through the shared request timeout and
+ * retry policy. A valid response without a compatible path returns no route.
+ * Discovery sends no events, so the caller can safely select direct intake
+ * after either result. The caller also owns later delivery failures. It can
+ * switch future batches after an ambiguous timeout or reset, but it must not
+ * replay the current batch because the first receiver might have accepted it.
+ *
+ * Reference implementations:
+ *
+ * Agent `/info` and EVP proxy:
+ * https://github.com/DataDog/datadog-agent/tree/main/pkg/trace/api
+ *
+ * serverless-init entry point and embedded trace receiver:
+ * https://github.com/DataDog/datadog-agent/blob/main/cmd/serverless-init/main.go
+ * https://github.com/DataDog/datadog-agent/blob/main/pkg/serverless/trace/trace.go
+ */
+
 /**
  * Selects the first advertised EVP proxy path that the caller supports.
  *
@@ -82,6 +121,7 @@ function discoverEVPProxy (url, options, callback) {
       return
     }
 
+    log.debug('EVP proxy route %s discovered through the configured local receiver', basePath)
     callback(null, { url, basePath })
   })
 }

packages/dd-trace/test/evp_proxy/discovery.spec.js

@@ -15,13 +15,16 @@ describe('EVP proxy discovery', () => {
 
   let discoverEVPProxy
   let fetchAgentInfo
+  let log
   let selectEVPProxyPath
 
   beforeEach(() => {
     fetchAgentInfo = sinon.stub()
+    log = { debug: sinon.stub() }
 
     const discovery = proxyquire('../../src/evp_proxy/discovery', {
       '../agent/info': { fetchAgentInfo },
+      '../log': log,
     })
 
     discoverEVPProxy = discovery.discoverEVPProxy
@@ -97,6 +100,11 @@ describe('EVP proxy discovery', () => {
           basePath: '/evp_proxy/v2',
         })
         sinon.assert.calledOnceWithExactly(fetchAgentInfo, url, sinon.match.func)
+        sinon.assert.calledOnceWithExactly(
+          log.debug,
+          'EVP proxy route %s discovered through the configured local receiver',
+          '/evp_proxy/v2'
+        )
         done()
       })
     })
@@ -107,6 +115,7 @@ describe('EVP proxy discovery', () => {
       discoverEVPProxy(url, options, (error, route) => {
         assert.ifError(error)
         assert.strictEqual(route, undefined)
+        sinon.assert.notCalled(log.debug)
         done()
       })
     })
@@ -118,6 +127,7 @@ describe('EVP proxy discovery', () => {
       discoverEVPProxy(url, options, (error, route) => {
         assert.strictEqual(error, expectedError)
         assert.strictEqual(route, undefined)
+        sinon.assert.notCalled(log.debug)
         done()
       })
     })