@fluidframework/app-insights-logger 2.0.0-dev.7.3.0.210328 → 2.0.0-rc.1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/README.md +1 -1
- package/api-extractor-esm.json +18 -0
- package/api-extractor-lint.json +4 -0
- package/api-extractor.json +1 -2
- package/api-report/app-insights-logger.api.md +6 -10
- package/dist/app-insights-logger-alpha.d.ts +130 -0
- package/dist/app-insights-logger-beta.d.ts +130 -0
- package/dist/app-insights-logger-public.d.ts +22 -0
- package/dist/app-insights-logger-untrimmed.d.ts +130 -0
- package/dist/fluidAppInsightsLogger.d.ts +11 -55
- package/dist/fluidAppInsightsLogger.d.ts.map +1 -1
- package/dist/fluidAppInsightsLogger.js +14 -3
- package/dist/fluidAppInsightsLogger.js.map +1 -1
- package/dist/index.d.ts +1 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -2
- package/dist/index.js.map +1 -1
- package/dist/tsdoc-metadata.json +1 -1
- package/lib/app-insights-logger-alpha.d.mts +124 -0
- package/lib/app-insights-logger-beta.d.mts +124 -0
- package/lib/app-insights-logger-public.d.mts +16 -0
- package/lib/app-insights-logger-untrimmed.d.mts +124 -0
- package/lib/{fluidAppInsightsLogger.d.ts → fluidAppInsightsLogger.d.mts} +12 -56
- package/lib/fluidAppInsightsLogger.d.mts.map +1 -0
- package/lib/{fluidAppInsightsLogger.js → fluidAppInsightsLogger.mjs} +14 -3
- package/lib/fluidAppInsightsLogger.mjs.map +1 -0
- package/lib/index.d.mts +7 -0
- package/lib/index.d.mts.map +1 -0
- package/lib/{index.js → index.mjs} +2 -2
- package/lib/index.mjs.map +1 -0
- package/lib/test/fluidAppInsightsLogger.spec.d.mts +2 -0
- package/lib/test/fluidAppInsightsLogger.spec.d.mts.map +1 -0
- package/lib/test/{fluidAppInsightsLogger.spec.js → fluidAppInsightsLogger.spec.mjs} +23 -27
- package/lib/test/fluidAppInsightsLogger.spec.mjs.map +1 -0
- package/package.json +87 -15
- package/src/fluidAppInsightsLogger.ts +22 -12
- package/src/index.ts +6 -7
- package/tsconfig.json +5 -3
- package/lib/fluidAppInsightsLogger.d.ts.map +0 -1
- package/lib/fluidAppInsightsLogger.js.map +0 -1
- package/lib/index.d.ts +0 -13
- package/lib/index.d.ts.map +0 -1
- package/lib/index.js.map +0 -1
- package/lib/test/fluidAppInsightsLogger.spec.d.ts +0 -2
- package/lib/test/fluidAppInsightsLogger.spec.d.ts.map +0 -1
- package/lib/test/fluidAppInsightsLogger.spec.js.map +0 -1
- package/tsconfig.esnext.json +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# @fluid-internal/app-insights-logger
|
|
2
2
|
|
|
3
|
+
## 2.0.0-rc.1.0.0
|
|
4
|
+
|
|
5
|
+
### Major Changes
|
|
6
|
+
|
|
7
|
+
- @fluid-experimental/app-insights-logger package renamed ([#18817](https://github.com/microsoft/FluidFramework/issues/18817)) [d1f584108b](https://github.com/microsoft/FluidFramework/commits/d1f584108bb93e73c355456d414d444c3641b7ab)
|
|
8
|
+
|
|
9
|
+
The package is now `@fluidframework/app-insights-logger`.
|
|
10
|
+
|
|
11
|
+
## 2.0.0-internal.8.0.0
|
|
12
|
+
|
|
13
|
+
Dependency updates only.
|
|
14
|
+
|
|
15
|
+
## 2.0.0-internal.7.4.0
|
|
16
|
+
|
|
17
|
+
Dependency updates only.
|
|
18
|
+
|
|
19
|
+
## 2.0.0-internal.7.3.0
|
|
20
|
+
|
|
21
|
+
Dependency updates only.
|
|
22
|
+
|
|
3
23
|
## 2.0.0-internal.7.2.0
|
|
4
24
|
|
|
5
25
|
Dependency updates only.
|
package/README.md
CHANGED
|
@@ -50,7 +50,7 @@ const appInsightsClient = new ApplicationInsights({
|
|
|
50
50
|
// Initializes the App Insights client. Without this, logs will not be sent to Azure.
|
|
51
51
|
appInsightsClient.loadAppInsights();
|
|
52
52
|
|
|
53
|
-
const logger = new
|
|
53
|
+
const logger = new createLogger(appInsightsClient);
|
|
54
54
|
|
|
55
55
|
// Example of sending an event to app insights using the FluidAppInsightsLogger directly
|
|
56
56
|
logger.send({ category: "mockEvent", eventName: "mockEventName" });
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
|
|
3
|
+
"extends": "../../../../common/build/build-common/api-extractor-base-esm.json",
|
|
4
|
+
"messages": {
|
|
5
|
+
"tsdocMessageReporting": {
|
|
6
|
+
// These exclusions are needed because of errors coming from @microsoft/applicationinsights-web
|
|
7
|
+
"tsdoc-escape-right-brace": {
|
|
8
|
+
"logLevel": "none"
|
|
9
|
+
},
|
|
10
|
+
"tsdoc-malformed-inline-tag": {
|
|
11
|
+
"logLevel": "none"
|
|
12
|
+
},
|
|
13
|
+
"tsdoc-undefined-tag": {
|
|
14
|
+
"logLevel": "none"
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
}
|
package/api-extractor.json
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
|
|
3
|
-
"extends": "
|
|
4
|
-
|
|
3
|
+
"extends": "../../../../common/build/build-common/api-extractor-base.json",
|
|
5
4
|
"messages": {
|
|
6
5
|
// The following overrides are workarounds for API-Extractor incorrectly running analysis on our application
|
|
7
6
|
// insights dependency.
|
|
@@ -5,22 +5,18 @@
|
|
|
5
5
|
```ts
|
|
6
6
|
|
|
7
7
|
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
|
|
8
|
-
import { ITelemetryBaseEvent } from '@fluidframework/core-interfaces';
|
|
9
8
|
import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
|
|
10
9
|
import { TelemetryEventCategory } from '@fluidframework/telemetry-utils';
|
|
11
10
|
|
|
12
|
-
// @
|
|
11
|
+
// @beta
|
|
13
12
|
export interface CategoryFilter {
|
|
14
13
|
categories: TelemetryEventCategory[];
|
|
15
14
|
}
|
|
16
15
|
|
|
17
|
-
// @
|
|
18
|
-
export
|
|
19
|
-
constructor(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig);
|
|
20
|
-
send(event: ITelemetryBaseEvent): void;
|
|
21
|
-
}
|
|
16
|
+
// @beta
|
|
17
|
+
export function createLogger(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig): ITelemetryBaseLogger;
|
|
22
18
|
|
|
23
|
-
// @
|
|
19
|
+
// @beta
|
|
24
20
|
export interface FluidAppInsightsLoggerConfig {
|
|
25
21
|
filtering: {
|
|
26
22
|
mode: "inclusive" | "exclusive";
|
|
@@ -28,7 +24,7 @@ export interface FluidAppInsightsLoggerConfig {
|
|
|
28
24
|
};
|
|
29
25
|
}
|
|
30
26
|
|
|
31
|
-
// @
|
|
27
|
+
// @beta
|
|
32
28
|
export interface NamespaceFilter {
|
|
33
29
|
namespacePattern: string;
|
|
34
30
|
namespacePatternExceptions?: Set<string>;
|
|
@@ -36,7 +32,7 @@ export interface NamespaceFilter {
|
|
|
36
32
|
|
|
37
33
|
export { TelemetryEventCategory }
|
|
38
34
|
|
|
39
|
-
// @
|
|
35
|
+
// @beta
|
|
40
36
|
export type TelemetryFilter = CategoryFilter | NamespaceFilter | (CategoryFilter & NamespaceFilter);
|
|
41
37
|
|
|
42
38
|
```
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This package provides a telemetry logger that will route typical Fluid telemetry to Azure App Insights.
|
|
3
|
+
* {@link https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview?tabs=net|Azure App Insights}
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
|
|
8
|
+
import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
|
|
9
|
+
import { TelemetryEventCategory } from '@fluidframework/telemetry-utils';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* A filter used to match against the category of a telemetry event
|
|
13
|
+
* @beta
|
|
14
|
+
*/
|
|
15
|
+
export declare interface CategoryFilter {
|
|
16
|
+
/**
|
|
17
|
+
* The categories of telemetry events that this filter applies to
|
|
18
|
+
*/
|
|
19
|
+
categories: TelemetryEventCategory[];
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Creates an {@link @fluidframework/core-interfaces#ITelemetryBaseLogger | ITelemetryBaseLogger}
|
|
24
|
+
* that routes Fluid telemetry events to Azure App Insights using the App Insights trackEvent API.
|
|
25
|
+
*
|
|
26
|
+
* The provided ApplicationInsights instance MUST be initialized with client.loadAppInsights(),
|
|
27
|
+
* or else logging will not occur.
|
|
28
|
+
*
|
|
29
|
+
* @beta
|
|
30
|
+
*/
|
|
31
|
+
export declare function createLogger(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig): ITelemetryBaseLogger;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The configuration object for creating the logger via {@link createLogger}.
|
|
35
|
+
* @beta
|
|
36
|
+
*/
|
|
37
|
+
export declare interface FluidAppInsightsLoggerConfig {
|
|
38
|
+
/**
|
|
39
|
+
* This Configuration defines how filtering will be applied to Fluid telemetry events flowing through the logger.
|
|
40
|
+
* This determines which events will be sent to Azure App Insights.
|
|
41
|
+
*/
|
|
42
|
+
filtering: {
|
|
43
|
+
/**
|
|
44
|
+
* Determines whether all telemetry events are sent or not sent by default and whether filters will exclude matching telemetry events or include them.
|
|
45
|
+
*
|
|
46
|
+
* "inclusive" mode means all logs are NOT SENT by default and only the events that match at least one or more specified filters WILL be sent (included).
|
|
47
|
+
*
|
|
48
|
+
* "exclusive" mode means all logs ARE SENT by default and only the events that match at least one or more specified filters WILL NOT be sent (excluded).
|
|
49
|
+
*/
|
|
50
|
+
mode: "inclusive" | "exclusive";
|
|
51
|
+
/**
|
|
52
|
+
* Controls the filtering of log events.
|
|
53
|
+
*
|
|
54
|
+
* @remarks Leaving this undefined will be treated as an empty array.
|
|
55
|
+
*
|
|
56
|
+
* In order for the filters to be valid they must meet the following conditions:
|
|
57
|
+
*
|
|
58
|
+
* 1. There must not be any two filters with the same `namespacePattern`.
|
|
59
|
+
*
|
|
60
|
+
* 2. All {@link NamespaceFilter} must not have any defined `namespacePatternException` that is not a child of the parent `namespacePattern`
|
|
61
|
+
*/
|
|
62
|
+
filters?: TelemetryFilter[];
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* A filter used to match against the namespaces of a telemetry event
|
|
68
|
+
* @beta
|
|
69
|
+
*/
|
|
70
|
+
export declare interface NamespaceFilter {
|
|
71
|
+
/**
|
|
72
|
+
* The namespace pattern to filter telemetry events.
|
|
73
|
+
*
|
|
74
|
+
* @remarks This will match namespaces that start with the given string. It is not a Regex pattern.
|
|
75
|
+
* @example
|
|
76
|
+
* "perf:latency" will match any namespace starting with "perf:latency"
|
|
77
|
+
*/
|
|
78
|
+
namespacePattern: string;
|
|
79
|
+
/**
|
|
80
|
+
* A list of namespace patterns to explicitly exclude from the filter.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* If you have a namespacePattern of "perf:latency" but want to exclude
|
|
84
|
+
* events from "perf:latency:ops", you would add "perf:latency:ops" to this list.
|
|
85
|
+
*/
|
|
86
|
+
namespacePatternExceptions?: Set<string>;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export { TelemetryEventCategory }
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Object used with an {@link FluidAppInsightsLoggerConfig}
|
|
93
|
+
* to define a filter with logic for matching it to telemetry events.
|
|
94
|
+
* Filters can include either a category, namespace or both types of filters; a valid filter must have at least one defined.
|
|
95
|
+
* Not definining the `categories` filter array is the same as providing an array with all possible categories.
|
|
96
|
+
*
|
|
97
|
+
* Events must satisify the following rules for a telemetry filter:
|
|
98
|
+
*
|
|
99
|
+
* 1. The event must match the requirements of the most specific relevant filter to it. This takes precedence over a more generic filter.
|
|
100
|
+
* The less categories and longer the namespace within a filter, the more specific it is. Definining no categories is equivalant to defining all categories.
|
|
101
|
+
*
|
|
102
|
+
* 2. If a {@link TelemetryFilter} specifies both `categories` and a `namespace`, the event must match both.
|
|
103
|
+
*
|
|
104
|
+
* 3. If only `categories` or a `namespace` is provided, the event should just match the with whatever was defined.
|
|
105
|
+
*
|
|
106
|
+
* 4. If a `namespace` pattern exception is specified in the {@link TelemetryFilter}, the event should not match the exception pattern.
|
|
107
|
+
* @example
|
|
108
|
+
* With the following configuration, an event `{ namespace: "A.B.C", categories: ["generic"] }` will not be sent despite matching the first, less specific filter because it did not match the second filter which was the most relevant and specific
|
|
109
|
+
* ```
|
|
110
|
+
* const logger = new FluidAppInsightsLogger(appInsightsClient, {
|
|
111
|
+
* filtering: {
|
|
112
|
+
* mode: "inclusive",
|
|
113
|
+
* filters: [
|
|
114
|
+
* {
|
|
115
|
+
* namespacePattern: "A:B",
|
|
116
|
+
* categories: ["generic", "error"],
|
|
117
|
+
* },
|
|
118
|
+
* {
|
|
119
|
+
* namespacePattern: "A:B:C",
|
|
120
|
+
* categories: ["error"],
|
|
121
|
+
* },
|
|
122
|
+
* ],
|
|
123
|
+
* },
|
|
124
|
+
* });
|
|
125
|
+
* ```
|
|
126
|
+
* @beta
|
|
127
|
+
*/
|
|
128
|
+
export declare type TelemetryFilter = CategoryFilter | NamespaceFilter | (CategoryFilter & NamespaceFilter);
|
|
129
|
+
|
|
130
|
+
export { }
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This package provides a telemetry logger that will route typical Fluid telemetry to Azure App Insights.
|
|
3
|
+
* {@link https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview?tabs=net|Azure App Insights}
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
|
|
8
|
+
import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
|
|
9
|
+
import { TelemetryEventCategory } from '@fluidframework/telemetry-utils';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* A filter used to match against the category of a telemetry event
|
|
13
|
+
* @beta
|
|
14
|
+
*/
|
|
15
|
+
export declare interface CategoryFilter {
|
|
16
|
+
/**
|
|
17
|
+
* The categories of telemetry events that this filter applies to
|
|
18
|
+
*/
|
|
19
|
+
categories: TelemetryEventCategory[];
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Creates an {@link @fluidframework/core-interfaces#ITelemetryBaseLogger | ITelemetryBaseLogger}
|
|
24
|
+
* that routes Fluid telemetry events to Azure App Insights using the App Insights trackEvent API.
|
|
25
|
+
*
|
|
26
|
+
* The provided ApplicationInsights instance MUST be initialized with client.loadAppInsights(),
|
|
27
|
+
* or else logging will not occur.
|
|
28
|
+
*
|
|
29
|
+
* @beta
|
|
30
|
+
*/
|
|
31
|
+
export declare function createLogger(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig): ITelemetryBaseLogger;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The configuration object for creating the logger via {@link createLogger}.
|
|
35
|
+
* @beta
|
|
36
|
+
*/
|
|
37
|
+
export declare interface FluidAppInsightsLoggerConfig {
|
|
38
|
+
/**
|
|
39
|
+
* This Configuration defines how filtering will be applied to Fluid telemetry events flowing through the logger.
|
|
40
|
+
* This determines which events will be sent to Azure App Insights.
|
|
41
|
+
*/
|
|
42
|
+
filtering: {
|
|
43
|
+
/**
|
|
44
|
+
* Determines whether all telemetry events are sent or not sent by default and whether filters will exclude matching telemetry events or include them.
|
|
45
|
+
*
|
|
46
|
+
* "inclusive" mode means all logs are NOT SENT by default and only the events that match at least one or more specified filters WILL be sent (included).
|
|
47
|
+
*
|
|
48
|
+
* "exclusive" mode means all logs ARE SENT by default and only the events that match at least one or more specified filters WILL NOT be sent (excluded).
|
|
49
|
+
*/
|
|
50
|
+
mode: "inclusive" | "exclusive";
|
|
51
|
+
/**
|
|
52
|
+
* Controls the filtering of log events.
|
|
53
|
+
*
|
|
54
|
+
* @remarks Leaving this undefined will be treated as an empty array.
|
|
55
|
+
*
|
|
56
|
+
* In order for the filters to be valid they must meet the following conditions:
|
|
57
|
+
*
|
|
58
|
+
* 1. There must not be any two filters with the same `namespacePattern`.
|
|
59
|
+
*
|
|
60
|
+
* 2. All {@link NamespaceFilter} must not have any defined `namespacePatternException` that is not a child of the parent `namespacePattern`
|
|
61
|
+
*/
|
|
62
|
+
filters?: TelemetryFilter[];
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* A filter used to match against the namespaces of a telemetry event
|
|
68
|
+
* @beta
|
|
69
|
+
*/
|
|
70
|
+
export declare interface NamespaceFilter {
|
|
71
|
+
/**
|
|
72
|
+
* The namespace pattern to filter telemetry events.
|
|
73
|
+
*
|
|
74
|
+
* @remarks This will match namespaces that start with the given string. It is not a Regex pattern.
|
|
75
|
+
* @example
|
|
76
|
+
* "perf:latency" will match any namespace starting with "perf:latency"
|
|
77
|
+
*/
|
|
78
|
+
namespacePattern: string;
|
|
79
|
+
/**
|
|
80
|
+
* A list of namespace patterns to explicitly exclude from the filter.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* If you have a namespacePattern of "perf:latency" but want to exclude
|
|
84
|
+
* events from "perf:latency:ops", you would add "perf:latency:ops" to this list.
|
|
85
|
+
*/
|
|
86
|
+
namespacePatternExceptions?: Set<string>;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export { TelemetryEventCategory }
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Object used with an {@link FluidAppInsightsLoggerConfig}
|
|
93
|
+
* to define a filter with logic for matching it to telemetry events.
|
|
94
|
+
* Filters can include either a category, namespace or both types of filters; a valid filter must have at least one defined.
|
|
95
|
+
* Not definining the `categories` filter array is the same as providing an array with all possible categories.
|
|
96
|
+
*
|
|
97
|
+
* Events must satisify the following rules for a telemetry filter:
|
|
98
|
+
*
|
|
99
|
+
* 1. The event must match the requirements of the most specific relevant filter to it. This takes precedence over a more generic filter.
|
|
100
|
+
* The less categories and longer the namespace within a filter, the more specific it is. Definining no categories is equivalant to defining all categories.
|
|
101
|
+
*
|
|
102
|
+
* 2. If a {@link TelemetryFilter} specifies both `categories` and a `namespace`, the event must match both.
|
|
103
|
+
*
|
|
104
|
+
* 3. If only `categories` or a `namespace` is provided, the event should just match the with whatever was defined.
|
|
105
|
+
*
|
|
106
|
+
* 4. If a `namespace` pattern exception is specified in the {@link TelemetryFilter}, the event should not match the exception pattern.
|
|
107
|
+
* @example
|
|
108
|
+
* With the following configuration, an event `{ namespace: "A.B.C", categories: ["generic"] }` will not be sent despite matching the first, less specific filter because it did not match the second filter which was the most relevant and specific
|
|
109
|
+
* ```
|
|
110
|
+
* const logger = new FluidAppInsightsLogger(appInsightsClient, {
|
|
111
|
+
* filtering: {
|
|
112
|
+
* mode: "inclusive",
|
|
113
|
+
* filters: [
|
|
114
|
+
* {
|
|
115
|
+
* namespacePattern: "A:B",
|
|
116
|
+
* categories: ["generic", "error"],
|
|
117
|
+
* },
|
|
118
|
+
* {
|
|
119
|
+
* namespacePattern: "A:B:C",
|
|
120
|
+
* categories: ["error"],
|
|
121
|
+
* },
|
|
122
|
+
* ],
|
|
123
|
+
* },
|
|
124
|
+
* });
|
|
125
|
+
* ```
|
|
126
|
+
* @beta
|
|
127
|
+
*/
|
|
128
|
+
export declare type TelemetryFilter = CategoryFilter | NamespaceFilter | (CategoryFilter & NamespaceFilter);
|
|
129
|
+
|
|
130
|
+
export { }
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This package provides a telemetry logger that will route typical Fluid telemetry to Azure App Insights.
|
|
3
|
+
* {@link https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview?tabs=net|Azure App Insights}
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
|
|
8
|
+
import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
|
|
9
|
+
import { TelemetryEventCategory } from '@fluidframework/telemetry-utils';
|
|
10
|
+
|
|
11
|
+
/* Excluded from this release type: CategoryFilter */
|
|
12
|
+
|
|
13
|
+
/* Excluded from this release type: createLogger */
|
|
14
|
+
|
|
15
|
+
/* Excluded from this release type: FluidAppInsightsLoggerConfig */
|
|
16
|
+
|
|
17
|
+
/* Excluded from this release type: NamespaceFilter */
|
|
18
|
+
export { TelemetryEventCategory }
|
|
19
|
+
|
|
20
|
+
/* Excluded from this release type: TelemetryFilter */
|
|
21
|
+
|
|
22
|
+
export { }
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This package provides a telemetry logger that will route typical Fluid telemetry to Azure App Insights.
|
|
3
|
+
* {@link https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview?tabs=net|Azure App Insights}
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
|
|
8
|
+
import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
|
|
9
|
+
import { TelemetryEventCategory } from '@fluidframework/telemetry-utils';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* A filter used to match against the category of a telemetry event
|
|
13
|
+
* @beta
|
|
14
|
+
*/
|
|
15
|
+
export declare interface CategoryFilter {
|
|
16
|
+
/**
|
|
17
|
+
* The categories of telemetry events that this filter applies to
|
|
18
|
+
*/
|
|
19
|
+
categories: TelemetryEventCategory[];
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Creates an {@link @fluidframework/core-interfaces#ITelemetryBaseLogger | ITelemetryBaseLogger}
|
|
24
|
+
* that routes Fluid telemetry events to Azure App Insights using the App Insights trackEvent API.
|
|
25
|
+
*
|
|
26
|
+
* The provided ApplicationInsights instance MUST be initialized with client.loadAppInsights(),
|
|
27
|
+
* or else logging will not occur.
|
|
28
|
+
*
|
|
29
|
+
* @beta
|
|
30
|
+
*/
|
|
31
|
+
export declare function createLogger(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig): ITelemetryBaseLogger;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The configuration object for creating the logger via {@link createLogger}.
|
|
35
|
+
* @beta
|
|
36
|
+
*/
|
|
37
|
+
export declare interface FluidAppInsightsLoggerConfig {
|
|
38
|
+
/**
|
|
39
|
+
* This Configuration defines how filtering will be applied to Fluid telemetry events flowing through the logger.
|
|
40
|
+
* This determines which events will be sent to Azure App Insights.
|
|
41
|
+
*/
|
|
42
|
+
filtering: {
|
|
43
|
+
/**
|
|
44
|
+
* Determines whether all telemetry events are sent or not sent by default and whether filters will exclude matching telemetry events or include them.
|
|
45
|
+
*
|
|
46
|
+
* "inclusive" mode means all logs are NOT SENT by default and only the events that match at least one or more specified filters WILL be sent (included).
|
|
47
|
+
*
|
|
48
|
+
* "exclusive" mode means all logs ARE SENT by default and only the events that match at least one or more specified filters WILL NOT be sent (excluded).
|
|
49
|
+
*/
|
|
50
|
+
mode: "inclusive" | "exclusive";
|
|
51
|
+
/**
|
|
52
|
+
* Controls the filtering of log events.
|
|
53
|
+
*
|
|
54
|
+
* @remarks Leaving this undefined will be treated as an empty array.
|
|
55
|
+
*
|
|
56
|
+
* In order for the filters to be valid they must meet the following conditions:
|
|
57
|
+
*
|
|
58
|
+
* 1. There must not be any two filters with the same `namespacePattern`.
|
|
59
|
+
*
|
|
60
|
+
* 2. All {@link NamespaceFilter} must not have any defined `namespacePatternException` that is not a child of the parent `namespacePattern`
|
|
61
|
+
*/
|
|
62
|
+
filters?: TelemetryFilter[];
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* A filter used to match against the namespaces of a telemetry event
|
|
68
|
+
* @beta
|
|
69
|
+
*/
|
|
70
|
+
export declare interface NamespaceFilter {
|
|
71
|
+
/**
|
|
72
|
+
* The namespace pattern to filter telemetry events.
|
|
73
|
+
*
|
|
74
|
+
* @remarks This will match namespaces that start with the given string. It is not a Regex pattern.
|
|
75
|
+
* @example
|
|
76
|
+
* "perf:latency" will match any namespace starting with "perf:latency"
|
|
77
|
+
*/
|
|
78
|
+
namespacePattern: string;
|
|
79
|
+
/**
|
|
80
|
+
* A list of namespace patterns to explicitly exclude from the filter.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* If you have a namespacePattern of "perf:latency" but want to exclude
|
|
84
|
+
* events from "perf:latency:ops", you would add "perf:latency:ops" to this list.
|
|
85
|
+
*/
|
|
86
|
+
namespacePatternExceptions?: Set<string>;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export { TelemetryEventCategory }
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Object used with an {@link FluidAppInsightsLoggerConfig}
|
|
93
|
+
* to define a filter with logic for matching it to telemetry events.
|
|
94
|
+
* Filters can include either a category, namespace or both types of filters; a valid filter must have at least one defined.
|
|
95
|
+
* Not definining the `categories` filter array is the same as providing an array with all possible categories.
|
|
96
|
+
*
|
|
97
|
+
* Events must satisify the following rules for a telemetry filter:
|
|
98
|
+
*
|
|
99
|
+
* 1. The event must match the requirements of the most specific relevant filter to it. This takes precedence over a more generic filter.
|
|
100
|
+
* The less categories and longer the namespace within a filter, the more specific it is. Definining no categories is equivalant to defining all categories.
|
|
101
|
+
*
|
|
102
|
+
* 2. If a {@link TelemetryFilter} specifies both `categories` and a `namespace`, the event must match both.
|
|
103
|
+
*
|
|
104
|
+
* 3. If only `categories` or a `namespace` is provided, the event should just match the with whatever was defined.
|
|
105
|
+
*
|
|
106
|
+
* 4. If a `namespace` pattern exception is specified in the {@link TelemetryFilter}, the event should not match the exception pattern.
|
|
107
|
+
* @example
|
|
108
|
+
* With the following configuration, an event `{ namespace: "A.B.C", categories: ["generic"] }` will not be sent despite matching the first, less specific filter because it did not match the second filter which was the most relevant and specific
|
|
109
|
+
* ```
|
|
110
|
+
* const logger = new FluidAppInsightsLogger(appInsightsClient, {
|
|
111
|
+
* filtering: {
|
|
112
|
+
* mode: "inclusive",
|
|
113
|
+
* filters: [
|
|
114
|
+
* {
|
|
115
|
+
* namespacePattern: "A:B",
|
|
116
|
+
* categories: ["generic", "error"],
|
|
117
|
+
* },
|
|
118
|
+
* {
|
|
119
|
+
* namespacePattern: "A:B:C",
|
|
120
|
+
* categories: ["error"],
|
|
121
|
+
* },
|
|
122
|
+
* ],
|
|
123
|
+
* },
|
|
124
|
+
* });
|
|
125
|
+
* ```
|
|
126
|
+
* @beta
|
|
127
|
+
*/
|
|
128
|
+
export declare type TelemetryFilter = CategoryFilter | NamespaceFilter | (CategoryFilter & NamespaceFilter);
|
|
129
|
+
|
|
130
|
+
export { }
|
|
@@ -3,12 +3,11 @@
|
|
|
3
3
|
* Licensed under the MIT License.
|
|
4
4
|
*/
|
|
5
5
|
import { type ApplicationInsights } from "@microsoft/applicationinsights-web";
|
|
6
|
-
import { type
|
|
6
|
+
import { type ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
|
|
7
7
|
import { type TelemetryEventCategory } from "@fluidframework/telemetry-utils";
|
|
8
8
|
/**
|
|
9
|
-
* The configuration object for the {@link
|
|
10
|
-
*
|
|
11
|
-
* @public
|
|
9
|
+
* The configuration object for creating the logger via {@link createLogger}.
|
|
10
|
+
* @beta
|
|
12
11
|
*/
|
|
13
12
|
export interface FluidAppInsightsLoggerConfig {
|
|
14
13
|
/**
|
|
@@ -40,8 +39,7 @@ export interface FluidAppInsightsLoggerConfig {
|
|
|
40
39
|
}
|
|
41
40
|
/**
|
|
42
41
|
* A filter used to match against the category of a telemetry event
|
|
43
|
-
*
|
|
44
|
-
* @public
|
|
42
|
+
* @beta
|
|
45
43
|
*/
|
|
46
44
|
export interface CategoryFilter {
|
|
47
45
|
/**
|
|
@@ -51,8 +49,7 @@ export interface CategoryFilter {
|
|
|
51
49
|
}
|
|
52
50
|
/**
|
|
53
51
|
* A filter used to match against the namespaces of a telemetry event
|
|
54
|
-
*
|
|
55
|
-
* @public
|
|
52
|
+
* @beta
|
|
56
53
|
*/
|
|
57
54
|
export interface NamespaceFilter {
|
|
58
55
|
/**
|
|
@@ -88,9 +85,6 @@ export interface NamespaceFilter {
|
|
|
88
85
|
* 3. If only `categories` or a `namespace` is provided, the event should just match the with whatever was defined.
|
|
89
86
|
*
|
|
90
87
|
* 4. If a `namespace` pattern exception is specified in the {@link TelemetryFilter}, the event should not match the exception pattern.
|
|
91
|
-
*
|
|
92
|
-
* @public
|
|
93
|
-
*
|
|
94
88
|
* @example
|
|
95
89
|
* With the following configuration, an event `{ namespace: "A.B.C", categories: ["generic"] }` will not be sent despite matching the first, less specific filter because it did not match the second filter which was the most relevant and specific
|
|
96
90
|
* ```
|
|
@@ -110,55 +104,17 @@ export interface NamespaceFilter {
|
|
|
110
104
|
* },
|
|
111
105
|
* });
|
|
112
106
|
* ```
|
|
107
|
+
* @beta
|
|
113
108
|
*/
|
|
114
109
|
export type TelemetryFilter = CategoryFilter | NamespaceFilter | (CategoryFilter & NamespaceFilter);
|
|
115
110
|
/**
|
|
116
|
-
*
|
|
111
|
+
* Creates an {@link @fluidframework/core-interfaces#ITelemetryBaseLogger | ITelemetryBaseLogger}
|
|
117
112
|
* that routes Fluid telemetry events to Azure App Insights using the App Insights trackEvent API.
|
|
118
|
-
*
|
|
113
|
+
*
|
|
114
|
+
* The provided ApplicationInsights instance MUST be initialized with client.loadAppInsights(),
|
|
119
115
|
* or else logging will not occur.
|
|
120
116
|
*
|
|
121
|
-
* @
|
|
122
|
-
* @public
|
|
117
|
+
* @beta
|
|
123
118
|
*/
|
|
124
|
-
export declare
|
|
125
|
-
/**
|
|
126
|
-
* The Azure ApplicationInsights client utilized by this logger.
|
|
127
|
-
* The ApplicationInsights instance MUST be initialized with client.loadAppInsights()
|
|
128
|
-
* or else logging will not occur.
|
|
129
|
-
*/
|
|
130
|
-
private readonly baseLoggingClient;
|
|
131
|
-
private readonly config;
|
|
132
|
-
constructor(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig);
|
|
133
|
-
/**
|
|
134
|
-
* Routes Fluid telemetry events to the trackEvent App Insights API.
|
|
135
|
-
* This method also uses the provided {@link FluidAppInsightsLoggerConfig} to
|
|
136
|
-
* determine whether an event should be sent or not.
|
|
137
|
-
*/
|
|
138
|
-
send(event: ITelemetryBaseEvent): void;
|
|
139
|
-
private shouldSendEvent;
|
|
140
|
-
/**
|
|
141
|
-
* Checks if a given telemetry event conforms to any of the provided {@link TelemetryFilter} rules.
|
|
142
|
-
*
|
|
143
|
-
* 1. The event must match the requirements of the most specific relevant filter to it. This takes precedence over a more generic filter.
|
|
144
|
-
* The less categories and longer the namespace within a filter, the more specific it is. Definining no categories is equivalant to defining all categories.
|
|
145
|
-
*
|
|
146
|
-
* 2. If a {@link TelemetryFilter} specifies both `categories` and a `namespace`, the event must match both.
|
|
147
|
-
*
|
|
148
|
-
* 3. If only `categories` or a `namespace` is provided, the event should match either one of them.
|
|
149
|
-
*
|
|
150
|
-
* 4. If a `namespace` pattern exception is specified in the {@link TelemetryFilter}, the event should not match the exception pattern.
|
|
151
|
-
*
|
|
152
|
-
* @param event - The telemetry event to check against the filters.
|
|
153
|
-
*
|
|
154
|
-
* @returns `true` if the event matches any filter, otherwise `false`.
|
|
155
|
-
*/
|
|
156
|
-
private doesEventMatchFilter;
|
|
157
|
-
/**
|
|
158
|
-
* Checks an array of telemetry filters for any issues, merges redundant filters, and returns a fully validated array.
|
|
159
|
-
*
|
|
160
|
-
* @throws An Error if there are two filters with duplicate namespace patterns or a filter with a pattern exception that is not a child of the parent pattern.
|
|
161
|
-
*/
|
|
162
|
-
private validateFilters;
|
|
163
|
-
}
|
|
119
|
+
export declare function createLogger(client: ApplicationInsights, config?: FluidAppInsightsLoggerConfig): ITelemetryBaseLogger;
|
|
164
120
|
//# sourceMappingURL=fluidAppInsightsLogger.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"fluidAppInsightsLogger.d.ts","sourceRoot":"","sources":["../src/fluidAppInsightsLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,
|
|
1
|
+
{"version":3,"file":"fluidAppInsightsLogger.d.ts","sourceRoot":"","sources":["../src/fluidAppInsightsLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAEN,KAAK,oBAAoB,EACzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC5C;;;OAGG;IACH,SAAS,EAAE;QACV;;;;;;WAMG;QACH,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;QAChC;;;;;;;;;;WAUG;QACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;KAC5B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,CAAC,cAAc,GAAG,eAAe,CAAC,CAAC;AA6LpG;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,CAAC,EAAE,4BAA4B,GACnC,oBAAoB,CAEtB"}
|