Skip to content

Add CfgSync documentation #2721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add CfgSync documentation #2721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
608eb28
Initial plan
Copilot Apr 8, 2026
a358903
Add documentation for CfgSync plugin and fix example build issue
Copilot Apr 8, 2026
e944413
Revert build pipeline changes (package.json, rollup.config.js) per re…
Copilot Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ but may not be executed as part of any automated test pass -- this may change/va

[Dependency](./dependency/README.md)

[CfgSync Plugin](./cfgSync/README.md)

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to
Expand Down
115 changes: 111 additions & 4 deletions extensions/applicationinsights-cfgsync-js/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,116 @@
[![Build Status](https://dev.azure.com/mseng/AppInsights/_apis/build/status/AppInsights%20-%20DevTools/1DS%20JavaScript%20SDK%20web%20SKU%20vNext?branchName=main)](https://dev.azure.com/mseng/AppInsights/_build/latest?definitionId=8184&branchName=main)
[![npm version](https://badge.fury.io/js/%40microsoft%2Fapplicationinsights-cfgsync-js.svg)](https://badge.fury.io/js/%40microsoft%2Fapplicationinsights-cfgsync-js)

Application Insights CfgSync Plugin enables configuration change communication among mutiple instances.
Application Insights CfgSync Plugin enables configuration change communication among multiple instances.
Refer to [our GitHub page](https://github.com/microsoft/ApplicationInsights-JS) for more details on getting started.

## Getting Started

### Installation

```sh
npm install @microsoft/applicationinsights-cfgsync-js
```

### Basic Usage

The CfgSync Plugin supports three synchronization modes:

- **Broadcast** (default): The instance broadcasts its configuration changes to other instances.
- **Receive**: The instance only receives configuration changes from broadcasting instances.
- **None**: The instance neither broadcasts nor receives configuration changes.
Comment on lines +21 to +25
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section documents three modes including None, but the rest of the Getting Started examples only demonstrate Broadcast/Receive/CDN fetch. To avoid leaving readers without guidance, either add a short snippet showing how to configure syncMode: ICfgSyncMode.None, or remove the None bullet from this introductory list.

Copilot uses AI. Check for mistakes.

#### Broadcasting Instance

The main (broadcaster) instance sends configuration updates to all listener instances:

```typescript
import { ApplicationInsights } from "@microsoft/applicationinsights-web";
import { CfgSyncPlugin, ICfgSyncConfig, ICfgSyncMode } from "@microsoft/applicationinsights-cfgsync-js";

const cfgSyncPlugin = new CfgSyncPlugin();

const appInsights = new ApplicationInsights({
config: {
connectionString: "InstrumentationKey=YOUR_KEY",
extensions: [cfgSyncPlugin],
extensionConfig: {
[cfgSyncPlugin.identifier]: {
syncMode: ICfgSyncMode.Broadcast
} as ICfgSyncConfig
}
}
});
appInsights.loadAppInsights();
```

#### Receiving Instance

Listener instances receive and apply configuration updates from broadcasting instances. Use `nonOverrideConfigs` to protect specific fields from being overwritten:

```typescript
import { ApplicationInsights } from "@microsoft/applicationinsights-web";
import { CfgSyncPlugin, ICfgSyncConfig, ICfgSyncMode } from "@microsoft/applicationinsights-cfgsync-js";

const cfgSyncPlugin = new CfgSyncPlugin();

const listenerAppInsights = new ApplicationInsights({
config: {
connectionString: "InstrumentationKey=LISTENER_KEY",
extensions: [cfgSyncPlugin],
extensionConfig: {
[cfgSyncPlugin.identifier]: {
syncMode: ICfgSyncMode.Receive,
nonOverrideConfigs: {
connectionString: true,
instrumentationKey: true,
endpointUrl: true
}
} as ICfgSyncConfig
}
}
});
listenerAppInsights.loadAppInsights();
```

#### Fetching Configuration from a CDN Endpoint

You can configure an instance to fetch its configuration from a remote URL:

```typescript
import { ApplicationInsights } from "@microsoft/applicationinsights-web";
import { CfgSyncPlugin, ICfgSyncConfig } from "@microsoft/applicationinsights-cfgsync-js";

const cfgSyncPlugin = new CfgSyncPlugin();

const appInsights = new ApplicationInsights({
config: {
connectionString: "InstrumentationKey=YOUR_KEY",
extensions: [cfgSyncPlugin],
extensionConfig: {
[cfgSyncPlugin.identifier]: {
cfgUrl: "https://your-cdn-endpoint/config.json",
scheduleFetchTimeout: 1800000 // re-fetch every 30 minutes
} as ICfgSyncConfig
}
}
});
appInsights.loadAppInsights();
```

The CDN endpoint should return a JSON object following the `ICfgSyncCdnConfig` interface.

### Plugin API

| Method | Description |
|--------|-------------|
| `getCfg()` | Returns the current configuration of this instance. |
| `setCfg(config)` | Manually sets the configuration of this instance. Returns `true` on success. |
| `sync(customDetails?)` | Manually broadcasts the current configuration to all listener instances. Returns `true` on success. |
| `pause()` | Pauses the scheduled CDN fetch timer. |
| `resume()` | Resumes the scheduled CDN fetch timer. |
| `updateEventListenerName(eventName?)` | Updates the custom event name used to broadcast/receive configuration changes. |
Comment on lines +109 to +116
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Plugin API markdown table uses || at the start of each row, which GitHub Markdown interprets as an extra empty column (or can render incorrectly). Please switch this to standard table formatting (single leading pipe, or no leading/trailing pipes consistently), e.g. | Method | Description | with | --- | --- |.

Copilot uses AI. Check for mistakes.

## [Configuration](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html)

| Name | Type | Default | Description |
Expand All @@ -19,7 +126,7 @@ Refer to [our GitHub page](https://github.com/microsoft/ApplicationInsights-JS)
| [onCfgChangeReceive](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html#onCfgChangeReceive) | function<br>[Optional] | null | Overrides callback function to handle event details when changes are received via event listener. |
| [overrideSyncFn](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html#overrideSyncFn) | function<br>[Optional] | null | Overrides sync() function to broadcast changes. |
| [overrideFetchFn](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html#overrideFetchFn) | function<br>[Optional] | null | Overrides fetch function to get config from cfgUrl when cfgUrl is defined. |
| [nonOverrideConfigs](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html#nonOverrideConfigs) | NonOverrideCfg<br>[Optional] | {instrumentationKey: true, connectionString: true, endpointUrl: true } | When current instance is set with syncMode: `Receive`, config fields under nonOverrideConfigs will NOT be changed by any confif details sent out from other instances. NOTE: this config will be ONLY applied during initialization, so it won't be changed dynamically. |
| [nonOverrideConfigs](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html#nonOverrideConfigs) | NonOverrideCfg<br>[Optional] | {instrumentationKey: true, connectionString: true, endpointUrl: true } | When current instance is set with syncMode: `Receive`, config fields under nonOverrideConfigs will NOT be changed by any config details sent out from other instances. NOTE: this config will be ONLY applied during initialization, so it won't be changed dynamically. |
| [scheduleFetchTimeout](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-cfgsync-js/interfaces/ICfgSyncConfig.html#scheduleFetchTimeout) | number<br>[Optional] | 30 mins | Identifies the time interval (in milliseconds) for fetching config details from cfgUrl when cfgUrl is defined. If set to 0, the fetch operation will only be called once during initialization. |


Expand All @@ -42,11 +149,11 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi

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.
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](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). 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.
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](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). 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

Expand Down
Loading