feat: Azure Functions (#3071)

Support for tracing/monitoring Azure Functions.
Supported triggers/bindings: HTTP (spec'd), Timer (not spec'd).

Spec: elastic/apm#716
Closes: #3015
Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

.eslintrc.json

@@ -18,6 +18,7 @@
     "/examples/esbuild/dist",
     "/examples/typescript/dist",
     "/examples/nextjs",
+    "/examples/an-azure-function-app",
     "/lib/opentelemetry-bridge/opentelemetry-core-mini",
     "/test/babel/out.js",
     "/test/lambda/fixtures/esbuild-bundled-handler/hello.js",

CHANGELOG.asciidoc

@@ -32,6 +32,25 @@ Notes:
 === Node.js Agent version 3.x
 
 
+==== Unreleased
+
+[float]
+===== Breaking changes
+
+[float]
+===== Features
+
+* Support for tracing/monitoring https://learn.microsoft.com/en-us/azure/azure-functions/[Azure Functions].
+  See the <<azure-functions>> document.
+  ({pull}3071[#3071], https://github.com/elastic/apm/blob/main/specs/agents/tracing-instrumentation-azure-functions.md[spec])
+
+[float]
+===== Bug fixes
+
+[float]
+===== Chores
+
+
 [[release-notes-3.41.1]]
 ==== 3.41.1 2022/12/21
 

NOTICE.md

@@ -424,3 +424,37 @@ The above copyright notice and this permission notice shall be included in all c
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
+
+
+## require-in-the-middle
+
+- **path:** [lib/ritm.js](lib/ritm.js)
+- **author:** Thomas Watson Steen
+- **project url:** https://github.com/elastic/require-in-the-middle
+- **original file:** https://github.com/elastic/require-in-the-middle/blob/v5.2.0/index.js
+- **license:** MIT License (MIT), http://opensource.org/licenses/MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2016-2019 Thomas Watson Steen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+

docs/azure-functions.asciidoc

@@ -0,0 +1,155 @@
+:framework: Azure Functions
+
+[[azure-functions]]
+
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/azure-functions.html[elastic.co]
+endif::[]
+
+=== Monitoring Node.js Azure Functions
+
+The Node.js APM Agent can trace function invocations in an https://learn.microsoft.com/en-us/azure/azure-functions/[Azure Functions] app.
+
+
+[float]
+[[azure-functions-prerequisites]]
+==== Prerequisites
+
+You need an APM Server to send APM data to. Follow the
+{apm-guide-ref}/apm-quick-start.html[APM Quick start] if you have not set one up
+yet. You will need your *APM server URL* and an APM server *secret token* (or
+*API key*) for configuring the APM agent below.
+
+You will also need an Azure Function app to monitor. If you do not have an
+existing one, you can follow https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-node#create-supporting-azure-resources-for-your-function[this Azure guide]
+to create one.
+
+[IMPORTANT]
+====
+If you use `func init --javascript ...` as suggested in this Azure guide,
+then it is recommended that you *uninstall* the `azure-functions-core-tools`
+dependency by running `npm uninstall azure-functions-core-tools` and
+https://github.com/Azure/azure-functions-core-tools#installing[install it separately].
+Having `azure-functions-core-tools` as a "devDependency" in your package.json
+will result in unreasonably large deployments that will be very slow to publish
+and will run your Azure Function app VM out of disk space.
+====
+
+You can also take a look at and use this https://github.com/elastic/apm-agent-nodejs/tree/main/examples/an-azure-function-app/[Azure Functions example app with Elastic APM already integrated].
+
+[float]
+[[azure-functions-setup]]
+==== Step 1: Add the APM agent dependency
+
+Add the `elastic-apm-node` module as a dependency of your application:
+
+[source,bash]
+----
+npm install elastic-apm-node --save  # or 'yarn add elastic-apm-node'
+----
+
+
+[float]
+==== Step 2: Start the APM agent
+
+For the APM agent to instrument Azure Functions, it needs to be started when the
+Azure host starts its Node.js worker processes. The best way to do so is by
+using an app-level entry point (support for this was added for Node.js Azure
+Functions https://github.com/Azure/azure-functions-nodejs-worker/issues/537[here]).
+
+1. Create a module to start the APM agent. For example, a file at the root of your repository named "initapm.js":
++
+[source,javascript]
+----
+// initapm.js
+require('elastic-apm-node').start({
+  <1>
+})
+----
+<1> Optional <<configuration,configuration options>> can be added here.
+
+2. Add a "main" entry to your package.json pointing to the app init file.
++
+[source,json]
+----
+...
+  "main": "initapm.js",
+...
+----
++
+If your application already has a "main" init file, you can instead add the
+`require('elastic-apm-node').start()` to top of that file.
+
+
+[float]
+==== Step 3: Configure the APM agent
+
+The APM agent can be <<configuring-the-agent,configured>> with options to the
+`.start()` method or with environment variables. Using environment variables
+allows one to use https://learn.microsoft.com/en-us/azure/azure-functions/functions-how-to-use-azure-function-app-settings?tabs=portal#settings[application settings in the Azure Portal] which allows hiding values and updating settings
+without needing to re-deploy code.
+
+Open _Configuration > Application settings_ for your Function App in the Azure Portal
+and set:
+
+[source,yaml]
+----
+ELASTIC_APM_SERVER_URL: <your APM server URL from the prerequisites step>
+ELASTIC_APM_SECRET_TOKEN: <your APM secret token from the prerequisites step>
+----
+
+For example:
+
+image::./images/azure-functions-configuration.png[Configuring the APM Agent in the Azure Portal]
+
+For local testing via `func start` you can set these environment variables in
+your terminal, or in the "local.settings.json" file. See the
+<<configuration,agent configuration guide>> for full details on supported
+configuration variables.
+
+
+[float]
+==== Step 4: (Re-)deploy your Azure Function app
+
+[source,bash]
+----
+func azure functionapp publish <APP_NAME>
+----
+
+Now, when you invoke your Azure Functions, you should see your application
+show up as a Service in the APM app in Kibana and see APM transactions for
+function invocations.  Tracing data is forwarded to APM server after a period
+of time, so allow a minute or so for data to appear.
+
+
+[float]
+[[azure-functions-limitations]]
+==== Limitations
+
+This instrumentation does not send an APM transaction or error to APM server when
+a handler has an `uncaughtException` or `unhandledRejection`.
+The Azure Functions Node.js reference https://learn.microsoft.com/en-ca/azure/azure-functions/functions-reference-node#use-async-and-await[has a section] with best practices for avoiding these cases.
+
+Azure Functions instrumentation currently does _not_ collect system metrics in
+the background because of a concern with unintentionally increasing Azure
+Functions costs (for Consumption plans).
+
+
+[float]
+[[azure-functions-filter-sensitive-information]]
+==== Filter sensitive information
+
+include::./shared-set-up.asciidoc[tag=filter-sensitive-info]
+
+[float]
+[[azure-functions-compatibility]]
+==== Compatibility
+
+include::./shared-set-up.asciidoc[tag=compatibility-link]
+
+[float]
+[[azure-functions-troubleshooting]]
+==== Troubleshooting
+
+include::./shared-set-up.asciidoc[tag=troubleshooting-link]

docs/set-up.asciidoc

@@ -7,14 +7,14 @@ To get you off the ground, we've prepared guides for setting up the Agent with a
 // Updates made here will be applied elsewhere as well.
 // tag::web-frameworks-list[]
 * <<lambda>>
+* <<azure-functions>>
 * <<express>>
 * <<fastify>>
 * <<hapi>>
 * <<koa>>
 * <<nextjs>>
 * <<restify>>
 * <<typescript>>
-* <<nextjs>>
 // end::web-frameworks-list[]
 
 Alternatively, you can <<custom-stack>>.
@@ -30,6 +30,8 @@ Other useful documentation includes:
 
 include::./lambda.asciidoc[]
 
+include::./azure-functions.asciidoc[]
+
 include::./express.asciidoc[]
 
 include::./fastify.asciidoc[]

docs/supported-technologies.asciidoc

@@ -88,6 +88,7 @@ These are the frameworks that we officially support:
 |=======================================================================
 | Framework             | Version | Note
 | <<lambda,AWS Lambda>> | N/A |
+| <<azure-functions,Azure Functions>> | ~4 | See https://learn.microsoft.com/en-ca/azure/azure-functions/set-runtime-version[the guide on Azure Functions runtime versions].
 | <<express,Express>>   | ^4.0.0 |
 | <<fastify,Fastify>>   | >=1.0.0 | See also https://www.fastify.io/docs/latest/Reference/LTS/[Fastify's own LTS documentation]
 | <<hapi,@hapi/hapi>>   | >=17.9.0 <22.0.0 |

examples/an-azure-function-app/.gitignore

@@ -0,0 +1,49 @@
+.vscode/
+
+bin
+obj
+csx
+.vs
+edge
+Publish
+
+*.user
+*.suo
+*.cscfg
+*.Cache
+project.lock.json
+
+/packages
+/TestResults
+
+/tools/NuGet.exe
+/App_Data
+/secrets
+/data
+.secrets
+appsettings.json
+
+node_modules
+dist
+
+# Local python packages
+.python_packages/
+
+# Python Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Azurite artifacts
+__blobstorage__
+__queuestorage__
+__azurite_db*__.json

examples/an-azure-function-app/.npmrc

@@ -0,0 +1 @@
+package-lock=false

examples/an-azure-function-app/Bye/function.json

@@ -0,0 +1,19 @@
+{
+  "bindings": [
+    {
+      "authLevel": "Anonymous",
+      "type": "httpTrigger",
+      "direction": "in",
+      "name": "req",
+      "methods": [
+        "get",
+        "post"
+      ]
+    },
+    {
+      "type": "http",
+      "direction": "out",
+      "name": "res"
+    }
+  ]
+}

examples/an-azure-function-app/Bye/index.js

@@ -0,0 +1,11 @@
+module.exports = async function (context, _req) {
+  const body = JSON.stringify({ good: 'bye' })
+  context.res = {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body)
+    },
+    body
+  }
+}

examples/an-azure-function-app/Hi/function.json

@@ -0,0 +1,19 @@
+{
+  "bindings": [
+    {
+      "authLevel": "Anonymous",
+      "type": "httpTrigger",
+      "direction": "in",
+      "name": "req",
+      "methods": [
+        "get",
+        "post"
+      ]
+    },
+    {
+      "type": "http",
+      "direction": "out",
+      "name": "res"
+    }
+  ]
+}

examples/an-azure-function-app/Hi/index.js

@@ -0,0 +1,28 @@
+const http = require('http')
+const https = require('https')
+
+module.exports = async function (context, req) {
+  return new Promise((resolve, reject) => {
+    // Call the 'Bye' Function in this same Function App...
+    const url = new URL(req.url)
+    url.pathname = '/api/Bye'
+    const proto = (url.protocol === 'https:' ? https : http)
+    proto.get(url, res => {
+      res.resume()
+      res.on('error', reject)
+      res.on('end', () => {
+        // ... then respond.
+        const body = JSON.stringify({ hi: 'there' })
+        context.res = {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body)
+          },
+          body
+        }
+        resolve()
+      })
+    })
+  })
+}