Fix memory leak: clean up listeners on repeated useAzureMonitor calls (#1493)
- Fix memory leak: clean up listeners on repeated useAzureMonitor calls
When useAzureMonitor() is called multiple times, old AutoCollectExceptions and AutoCollectLogs instances were silently overwritten without cleanup, causing process event listener accumulation and retaining old LogApi instances (and their downstream spans/connection metadata) in memory.
This adds shutdown of previous instances before re-initialization and a test verifying listeners do not accumulate.
Fixes: https://github.com/microsoft/ApplicationInsights-node.js/issues/1415
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com
- Fix flaky test infrstructure.
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com
版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9
京公网安备 11010802032778号
Application Insights for Node.js
Application Insights SDK monitors your backend services and components after you deploy them to help you discover and rapidly diagnose performance and other issues. Add this SDK to your Node.js services to include deep info about Node.js processes and their external dependencies such as database and cache services. You can use this SDK for your Node.js services hosted anywhere: your datacenter, Azure VMs and Web Apps, and even other public clouds. This solution is based on OpenTelemetry, to learn more about OpenTelemetry concepts, see the OpenTelemetry overview or OpenTelemetry FAQ.
Supported Node.js versions
We support the versions of Node.js that are supported by OpenTelemetry.
Limitations of Application Insights 3.X SDK
In order to support importing version 3.X SDK as an ESM module, please follow the OpenTelemetry project’s documentation on using the instrumentation hook.
Consider whether this version is right for you. It enables distributed tracing, metrics, logs and excludes:
To determine if this version of Application Insights is right for you, review the Application Insights 2.X SDK migration guide.
Prerequisites
Azure subscription: Create an Azure subscription for free
Application Insights resource: Create an Application Insights resource
Application using an officially supported version of Node.js runtime:
Get started
appInsights.setup('YOUR_CONNECTION_STRING');, using the connection string you grabbed in step 2. Or put it in theAPPLICATIONINSIGHTS_CONNECTION_STRINGenvironment variable and callappInsights.setup()without parameters.appInsights.start();..setup()can be called with no arguments. This makes it easy to use different connection strings for different environments.Load the Application Insights library (i.e.
require("applicationinsights")) as early as possible in your scripts, before loading other packages. This is needed so that the Application Insights library can prepare later packages for tracking. If you encounter conflicts with other libraries doing similar preparation, try loading the Application Insights library after those.Understanding SDK Reliability with SDK Stats
The SDK stats feature helps you monitor the reliability of telemetry transmission from the Application Insights SDK to Azure Monitor. SDK stats provide visibility into telemetry ingestion, including success rates, throttling, and errors. This information is essential for understanding whether your application’s telemetry is being reliably delivered to Application Insights.
By analyzing SDK stats, you can:
To learn more about SDK stats, including how to access and interpret them, see SDK stats documentation.
Configuration
The appInsights object provides a number of methods to setup SDK behavior. They are listed in the following snippet with their default values.
Please review their descriptions in your IDE’s built-in type hinting, or applicationinsights.ts for detailed information on what these control, and optional secondary arguments.
Note that by default
setAutoCollectConsoleis configured to exclude calls toconsole.log(and otherconsolemethods). By default, only calls to supported third-party loggers (e.g.winston,bunyan) will be collected. You can change this behavior to include calls toconsolemethods by usingsetAutoCollectConsole(true, true).Note that by default
enableWebInstrumentationwill use the connection string for SDK initialization. If you want to use a different one, you can set it asenableWebInstrumentation(true, "your-connection-string").The TelemetryClient constructor accepts optional settings (e.g.,
{ useGlobalProviders?: boolean }, defaults totrue) and exposes aconfigproperty with many optional settings. Constructor options example:Client
configproperties can be set as follows:These properties are client specific, so you can configure
appInsights.defaultClientseparately from clients created withnew appInsights.TelemetryClient().http_proxyenvironment variable)https_proxyenvironment variable)15000)100)noPatchModulesto a comma separated list of packages to disable. e.g."noPatchModules": "console,redis"to avoid patching the console and redis packages. The following modules are available:azuresdk, bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg, andpg-pool. Visit the diagnostic-channel-publishers’ README for information about exactly which versions of these packages are patched.All these properties except aadTokenCredential could be configured using configuration file
applicationinsights.jsonlocated under root folder of applicationinsights package installation folder, Ex:node_modules/applicationinsights. These configuration values will be applied to all TelemetryClients created in the SDK.Custom JSON file could be provided using
APPLICATIONINSIGHTS_CONFIGURATION_FILEenvironment variable.Alternatively, instead of using a configuration file, you can specify the entire content of the JSON configuration via the environment variable
APPLICATIONINSIGHTS_CONFIGURATION_CONTENT.Sampling
By default, the SDK will send all collected data to the Application Insights service. If you collect a lot of data, you might want to enable sampling to reduce the amount of data sent. Set the
samplingPercentagefield on the Config object of a Client to accomplish this. SettingsamplingPercentageto 100 (the default) means all data will be sent, and 0 means nothing will be sent.If you are using automatic correlation, all data associated with a single request will be included or excluded as a unit.
Add code such as the following to enable sampling:
Automatic web Instrumentation
For node server with configuration
enableWebInstrumentationset totrueor environment variableAPPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true, web Instrumentation will be enabled on node server response when all of the following requirements are met:200.GET.Content-Typehtml.<head>and</head>Tags.Content-Encodingtype, and encoding type must be one ofgzip,brordeflate.web Instrumentation CDN endpoint can be changed by setting environment variable
APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints". web Instrumentation connection string can be changed by setting environment variableAPPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"Note: web Instrumentation may slow down server response time, especially when response size is large or response is compressed. For the case in which some middle layers are applied, it may result in web Instrumentation not working and original response will be returned.
Automatic third-party instrumentation
In order to track context across asynchronous calls, some changes are required in third party libraries such as mongodb and redis. By default ApplicationInsights will use the appropriate OpenTelemetry instrumentation for each library. This can be disabled by setting the
APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNELenvironment variable. Note that by setting that environment variable, events may no longer be correctly associated with the right operation. Individual instrumentations can be disabled by setting theAPPLICATION_INSIGHTS_NO_PATCH_MODULESenvironment variable to a comma separated list of packages to disable, e.g.APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redisto avoid patching theconsoleandredispackages.The following modules are available:
azuresdk,bunyan,console,mongodb,mongodb-core,mysql,redis,winston,pg, andpg-pool.Automatic instrumentation for several Azure SDKs is also enabled. Javascript Azure SDKs
The
bunyan,winston, andconsolepatches will generate Application Insights Trace events based on whethersetAutoCollectConsoleis enabled. The rest will generate Application Insights Dependency events based on whethersetAutoCollectDependenciesis enabled. Make sure thatapplicationinsightsis imported before any 3rd-party packages for them to be instrumented successfully.Live Metrics
To enable sending live metrics of your app to Azure, use
setSendLiveMetrics(true). Filtering of live metrics in the Portal is currently not supported.Track custom telemetry
You can track any request, event, metric or exception using the Application Insights client. Examples follow:
Note that custom properties are converted to their string representation before being sent, see Using properties for more information.
An example utility using
trackMetricto measure how long event loop scheduling takes:Self-diagnostics
“Self-diagnostics” refers to internal logging from Application Insights Node.js SDK.
This functionality can be helpful for spotting and diagnosing issues with Application Insights itself.
By default, Application Insights Node.js SDK logs at warning level to console, following code demonstrate how to enable debug logging as well and generate telemetry for internal logs:
Debug Logs could be enabled as well using APPLICATION_INSIGHTS_ENABLE_DEBUG_LOGS environment variable, and APPLICATION_INSIGHTS_DISABLE_WARNING_LOGS environment variable to disable warnings. Logs could be put into local file using
APPLICATIONINSIGHTS_LOG_DESTINATIONenvironment variable, supported values arefileandfile+console, a file namedapplicationinsights.logwill be generated on tmp folder by default, including all logs,/tmpfor *nix andUSERDIR/AppData/Local/Tempfor Windows. Log directory could be configured usingAPPLICATIONINSIGHTS_LOGDIRenvironment variable.ApplicationInsights 3.X SDK Unsupported Properties
Application Insights 3.X SDK will provide support path for customers who only require basic instrumentation as opposed to migrating to Azure Monitor OpenTelemetry. If unsupported methods are called, they are not breaking and your application will still run. Calling these unsupported methods will throw a warning that the method is not supported.
The following methods are called after using the below method.
And invoked via
appInsights.<METHOD_NAME>|Property |Support Status | | —————————-|————————————————————————————————————| | setDistributedTracingMode | AI only tracing mode is no longer supported. Migrate to using W3C_AND_AI tracing mode. | | setAutoCollectHeartbeat | Heartbeat is not supported in either Azure Monitor OpenTelemetry or the Application Insights 3.X SDK.| | setAutoDependencyCorrelation| Turning off autoDependencyCorrelation is not supported by either Azure Monitor OpenTelemetry or the Application Insights 3.X SDK. | | setUseDiskRetryCaching | While enabling/disabling offline storage is supported, setting the resend interval or the maxBytesOnDisk values are not supported in the Application Insights 3.X SDK or Azure Monitor OpenTelemetry. The SDK uses hardcoded defaults: resend interval of 60 seconds (1 minute) and maxBytesOnDisk of 50 MB. Cached files are retained for up to 2 days before being cleaned up. | | setAutoCollectIncomingRequestAzureFunctions | Auto collection of Azure Functions is not supported by the Application Insights 3.X SDK or Azure Monitor OpenTelemetry. |The following configurations are set using either environment variables, setting them in the
applicationinsights.jsonfile or by callingappInsights.defaultClient.config.<CONFIG_SETTING_VALUE>;.Distributed Tracing and Correlation
The SDK automatically correlates telemetry associated with a request by using a W3C trace context. When a request is processed, the SDK creates a context for that operation, including a unique identifier that helps correlate all telemetry related to that operation.
Frontend to Backend Correlation
When correlating between Frontend (e.g., using
@microsoft/applicationinsights-web) and Backend (using this SDK), the following headers are supported:traceparent00-traceId-spanId-flagstracestateHow Frontend-Backend Correlation Works
Frontend Setup: The frontend application (using
@microsoft/applicationinsights-web) automatically includes these headers in outgoing HTTP requests when properly configured withenableCorsCorrelation: true.Automatic Header Processing: When the backend receives a request, this SDK automatically:
traceparent,tracestate) from the incoming requestNo manual code is required in your backend application to maintain this correlation. The SDK handles all the correlation context management internally.
For more information about W3C Trace Context, see the W3C Trace Context specification.
The following methods are part of the
TelemetryClientclass. They can be called usingapplicationinsights.defaultClient.<METHOD_NAME>().APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELenvironment varialbe could be used to set desired log level, supporting the following values:NONE,ERROR,WARN,INFO,DEBUG,VERBOSEandALL.Logs could be put into local file using
APPLICATIONINSIGHTS_LOG_DESTINATIONenvironment variable, supported values arefileandfile+console, a file namedapplicationinsights.logwill be generated on tmp folder by default, including all logs,/tmpfor *nix andUSERDIR/AppData/Local/Tempfor Windows. Log directory could be configured usingAPPLICATIONINSIGHTS_LOGDIRenvironment variable.Support
For help and questions about using this project, please create a Support request issue on https://github.com/microsoft/ApplicationInsights-node.js/issues.
For OpenTelemetry issues, contact the OpenTelemetry JavaScript community directly. Support Policy
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Data Collection
As this SDK is designed to enable applications to perform data collection which is sent to the Microsoft collection endpoints the following is required to identify our privacy statement.
The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.
License
MIT