Microsoft.PowerPlatform.Tooling.BatchedTelemetry

Concrete implementation of an .

The members of this class are made virtual in order to allow for mocking in unit tests.

Extensions for instances.

Tracks a using tuple params syntax as syntax sugar alternative to constructing a new Dictionary.

Tracks a call to an action as a operation with default support for capturing execution time, failures due to execeptions and recording any exceptions (but not handling them).

Tracks a call to a func as a operation with default support for capturing execution time, failures due to execeptions and recording any exceptions (but not handling them).

Represents a product configuration error regarding telemetry.

Exception that is thrown when there is a failure in an application's telemetry.

Composes the AutomationAgent string for the ExecutingAssembly. This is a shortcut for calling

The assembly name of the product that represents the agent. The `Cloud_roleName` specified for telemetry purposes of the agent. If specified, it will be used as the productName in the agent string instead of the assembly name. Can be null.

Adds custom properties for tracking the product assembly information along with the process language cultures used.

Composes a short, easily parsable string that contains the assembly's name and version. The format is the same used for User-Agent headers, namely "{Name}/{Version}".

Indicates whether to use the to construct the version part of the output. Otherwise, uses the .

Parses an environment variable value that accepts "1", "0", "true", "false" (case insensitive) and returns its boolean value. When the value is not set, or is invalid, null is returned.

The environment value. i.e. true when the value is "1" or "true"; false when the value is "0" or "false"; otherwise, null.

An implementation that will verify operations get disposed in the correct order, avoiding hard to identify lost telemetry bugs.

Represents the connection information to an Application Insights resource.

Creates a new resource represented by the specified connection string.

The connection string for the App Insights resource as copied from the Azure Portal.

Gets the instrumentation key for this resource. This value is set by specifying the ;

Gets the connection string to use for this resource. The value should be set to the copy/paste from the Azure Portal's value for Connection String. Setting this will also set the property for backwards compatibility.

The data boundary (aka Azure Region) this resource belongs to. May be null.

The values for this property can be found via the MSGraph `/organization` entity's `dataBoundary` privileged property.
At the time of writing, the only supported value is "EU", but others may be applicable in the future.

Initializes telemetry with the value of a telemetry source (aka SyntheticSource).

Creates a new instance using the passed in instance and initializers for the minimum required setup for a client app.

An optional mapping from the to a SyntheticSource. Callers should perform their own logic on the returned configuration for functionality like: - Flushing and disposing of the TelemetryConfiguration, as it is IDisposable and controls when the channel batched data will get flushed.

Most tools don't expose the ability to modify the users configuration settings, so this helper simplifies calling code by just getting it from the default location.

Composes the folder path to the shared telemetry cache folder for the passed in product assembly.

The assembly representing this product. It's name is used as a sub-folder path. The default uses . The full path to the cache folder.

Composes the folder path to the shared telemetry cache folder for the passed in product assembly.

The product name to use when creating the sub-folder for the cache. The default uses . The full path to the cache folder.

Indicates that this process should opt out of telemetry.

Initializes common telemetry context for a client app by setting global context values.

The 'cloud_RoleName' value in Application Insights. The assembly describing the product or execution program that created the session. Unique id for the current process. If not explicitly specified, will create a new one. By default, the roleInstance is redacted so we don't capture the user's machine name. Set this explicitly to null if you'd like to use the current machine name

The settings parsed from the current environment. When derived from environment variables these values should use the global env variable names specified in . Each application may choose to also implement their own environment variables or other source for getting these settings. e.g. the Pac CLI may choose to have its own env vars with a different prefix like "PAC_CLI_*". In this case, it's recommended to still use the global env variable names ("PP_TOOLS_*") for when the app-specific variables are not set.

Indicates that this process should opt out of telemetry.

The data boundary region for which all telemetry should be sent.

The values supported here piggy-back on the AAD Organization's `dataBoundary` property. If an application doesn't support this data boundary, then the default for the application will be used.

The 'User-Agent' string representing the automation agent calling the current program. The syntax of this value should be in the same format expected for HTTP User-Agent header.

The 'TelemetrySource' as specified by the legacy env variable .

The unique id for the user logged in to the machine.

Indicates whether the user default for whether to enable telemetry.

Gets a snapshot of the current user settings.

Sets the configurable 'TelemetryEnabled' setting and persists to storage.

Indicates explicit setting for whether telemetry should be enabled for this user. Setting to `null` resets to the default per app.

This class contains utilities that can help simplify robust file management activities when multiple processes may be accessing the same file.

This is intentially an internal class so as to prevent unexpected breaking changes.

Initializes telemetry with the value of a telemetry source (aka SyntheticSource).

Immutable user settings for telemetry.

An implementation of that uses a file on disk as the persistent storage.

Gets the current user settings if available and able. Otherwise, returns a new settings instance with a new one-time uniqueId. This method will never throw.

The current valid user settings, or a temporary default instance.

An exception occurred interacting with the user settings file.

A client for creating telemetry around an underlying App Insights instance.

Converter that supports serializing any object as a JSON string. OneDS collector seems to fail ingestion silently when a data property is not a value type (string, number, boolean). So complex properties on a 'Data' object should be serialized as a JSON string. When the target data table supports a kusto 'dynamic' type, it'll get the parsed JSON object.

Common result codes for telemetry operations which are supported by the shared telemetry platform. These are based upon the enum, but are limited to codes that apply to a CLI app.

Care should be taken about translating http service result codes from services called from a CLI and whether the code should be passed thru or translated to a different code based on the application logic.

Indicates a bad command line was recieved (e.g. input error, invalid args, etc)

Indicates an unknown command or action by the user.

General internal application error, unknown, unhandled.

Indicates an error originating from code external to the application, usually coming from a service call.

Updates the and properties according to the specified .

A helper class that tracks custom start/stop events with support for capturing the duration, success and optionally a result code.

This class is especially helpful for tracking operations which may overlap in an asynchronous manner (which App Insights operations do not support).

Creates a new instance and immediately tracks the 'start' event.

The telemetry client The name of the 'start' event. The name of the 'stop' event. Custom properties passed to the 'start' event.

Indicates whether the operation represented by this instance was succesful. If is set, the default for this property is set to ; otherwise, `false`. If your app's logic doesn't match with the semantics of , simply set this value explicitly.

Optional value indicating a result code for the operation. This setting is only included if specified.

Gets the total elapsed time since the start of the current instance, in milliseconds.

The dictionary of properties that will be used to submit the results for the 'stop' event when this instance is disposed.

Tracks the 'stop' event, and incorporates the values of , , .

The folder path in which to find the uploader program. The default in a sub folder named 'bt-uploader' relative to where this assembly is located. Note: It is best to set this to a fully qualified path to remove ambiguity.

Set the number of seconds of idle time before the spawned uploader (called during a Flush/Dispose) will exit.

The maximum number of milliseconds to wait to see if the uploader process has exited with a failure. If the uploader process has failed, an exception will be thrown in this process. This is done as part of the call to the Dispose method. It's suggested to set this on DEBUG builds to help identify these kind of errors during development time. Most likely, this value need not be more than a couple seconds, as errors on process startup tend to happen quickly.

[For unit tests only] Setting this to true will prevent starting the upload process.

[For unit tests only]

[For unit tests only] When set to true, the output from the upload process will be capturable and available from after the process has exited.

[For unit tests only] Returns all the text from the upload process output. Note: each line is prepended with `ERR` or `OUT` to indicate which stream it came from.

The number of items currently contained in the buffer. These have not been flushed.

The maximum number of items that can be stored in the backlog to be sent. New items will get dropped once this limit is reached.

The transmitter implementation, which will be disposed when this instance is disposed.

Indicates whether will call before disposing.

When overridden in a derived class, allows the channel to perform validation on the item before sending to the internal buffer.
Note for implementers:
Consider logging invalid items to instead of throwing when in production.

The telemetry item about to be sent to buffer. True if the item is valid and should be sent to the buffer, false otherwise.

Called when there's an explicit request to flush the buffer.

Default implementation calls .

Called when the transmitter is being disposed. This will only be called once.

Common property names used for telemetry captured for shared tools. Note: The naming convention for properties (and metrics) is to use cammelCaseNames.

The property name used for events to allow us to track where an exception event was being recorded. Because it's possible to track an exception at multiple spots in the call stack, this can help to identify where in the call stack the exception is being tracked. This is esp helpful for helper functions that help capture the context but doesn't actually handle the exception, e.g. and its overloads.

The legacy name of the custom property used for indicating the telemetry source. New code should set the . Note: the legacy property name used TitleCase, so this one does too.

Common metric names used to telemetry captured for shared tools. Note: The naming convention for metrics is different than properties to align with common App Insights metrics.

Indicates the duration of some operation. Usually included as part of the 'end'/'stop' event that has a matching 'begin'/'start' event. This metric should have the same semantic as the duration captured by an AI operation (i.e. Request or Dependency). Most importantly, that the value should be in milliseconds.

Legacy name used to report the execution time of some arbitrary operation. New code should use instead.

This is the legacy env variable used by old ProcessLauncher implementations.

To opt out of telemetry, set this environment variable to `1` or `true`.

To specify a data boundary region for which all telemetry should be sent.

The values supported here piggy-back on the AAD Organization's `dataBoundary` property. If an application doesn't support this data boundary, then the default for the application will be used.

Common environment variable that identifies when a tool is being called by some parent tool or custom script. The syntax of this value should be in the same format expected for HTTP User-Agent header.

A no-op implementation of . It still provides callers the ability to access the property (set to a new instance) without getting a runtime exception.

A no-op implementation of

An implementation of an that is sink, in that events are stored here, but never sent along. This type can be especially useful for cases where only runtime inspection is necessary; e.g. from unit tests. It simplifies the setup code needed in order to intercept actual telemetry data sent.

A base implementation for many of the telemetry channels.

Performs a seudo flush operation, allowing the to be updated, and later verified. It will not change the underlying capture of the .

Clears all items sent by this instance and resets to 0. Useful for scenarios where a test would like to ignore all previous events, and only capture new events. Note: does not change state of whether this instance has been disposed already; use a new instance in that case.

When overridden in a derived class, allows the channel to perform validation on the item before sending to the internal buffer. Default implementation always returns true.

The telemetry item about to be sent to buffer. True if the item is valid and should be sent to the buffer, false otherwise.

Creates a new using minimal configs and the channel specified. The default channel uses .

The channel to use for the . If this is not specified, a is used in order to swallow events. A new instance.

Helper for working with the W3C trace-context spec.

Used for testing purposes.

Non-blocking send of telemetry item.

Set the number of seconds of idle time before the spawned uploader (called during a Flush/Dispose) will exit.

[For unit tests only] Setting this to true will prevent starting the upload process.

[For unit tests only]

[For unit tests only] Returns all the text from the upload process output. Note: each line is prepended with `ERR` or `OUT` to indicate which stream it came from.

Serializer for the OneDS using Microsoft Common Schema Version 4.0. Official documentation can be found at: https://1dsdocs.azurewebsites.net/schema/README.html

The 2-letter country code for a deployment geography. The string value is normalized to upper-case for comparison purposes.

Asia

China

UAE, South Africa, etc

European Union

North America

The 2-digit country code for the geography represented by this instance. Normalized to upper-case.

Parses the value string to a known value. This method allows returning the same instance for known values to allow for faster comparisons.

Mapping service for converting location strings to and s.

Maps the location to a .

true if a mapping exists from the specified .

The 2-letter country code for a deployment geography. The string value is normalized to upper-case for comparison purposes.

The 2-digit country code for the geography represented by this instance. Normalized to upper-case.

Parses the value string to a known value. This method allows returning the same instance for known values to allow for faster comparisons.

Gets the that should be used to route this telemetry item.

Uniquely qualified name of the Common Schema Part B event.

An identifier used to identify applications or other logical groupings of events.

The local time that the event was recorded.

Gets a POCO that will get serialized to JSON via the 'data' of Common Schema PartC. This class should utilize System.Text.Json attributes to control serialization.

Represents an object that supports initialization from .

This method is called when a module is registered with a .

A OneDS telemetry channel that catches any exceptions in the channel chain and logs the errors. This allows apps to choose to compose their own telemetry channel chain without having to worry about exceptions. For example, an app may choose to use this channel as the top-level channel in the chain, but only for non-DEBUG builds.

The OneCollector endpoints used for PPUX shell-telemetry. Source: https://dev.azure.com/msazure/OneAgile/_git/power-platform-ux?path=packages/shell-telemetry/src/Constants.ts Note the official endpoints can be found here: https://eng.ms/docs/products/geneva/collect/clientingestion/onboardingsteps/endpoints/configureuploaddestination

Domain: `us-mobile.events.data.microsoft.com`.

This is the EUDB compliant endpoint. Domain: `eu-mobile.events.data.microsoft.com`.

Fairfax DoJ (L4, GCC, GCC High, Trailblazer). Domain: `tb.events.data.microsoft.com`.

Fairfax DoD (L5, Pathfinder). Domain: `pf.events.data.microsoft.com`.

Domain: `collector.azure.cn`.

USNat (EX, AG08). Domain: `collector.azure.eaglex.ic.gov`.

USSec (RX, AG09). Domain: `collector.azure.microsoft.scloud`.

These are now deprecated and should not be used. See note titled "Do Not Use EMEA, NOAM, nor APAC Urls" on page at https://eng.ms/docs/products/geneva/collect/clientingestion/onboardingsteps/endpoints/configureuploaddestination

Domain: `noam.events.data.microsoft.com`.

Domain: `emea.events.data.microsoft.com`.

Domain: `apac.events.data.microsoft.com`.

See wellknown uri constants in .

When overridden in a derived class, allows the initialization of the telemetry item before it is sent.

When overridden in a derived class, allows validation of the telemetry item before it is sent and after all initialization has completed.

The fully initialized telemetry item about to be sent.

The telemetry channel owned by this instance. Setting the channel in this ctor also sets to true.

Use to set the telemetry channel for this configuration instance. Note: Setting via this property does not change the value of . Use the ctor if you'd like the channel to be owned, and therefore disposed by this instance.

Indicates whether the should get disposed when this configuration instance is disposed.

A OneDS telemetry channel that routes telemetry to different channels based on a property supplied by each supported telemetry item.

This class makes it possible for us to separate telemetry routing from being a top-level configuration concern.

Forces all inner channels to be created. By default, this class only creates channels when they are needed. This method allows testing and clients to force all channels to be created for their own purposes. e.g. in Debug mode, to ensure tesing with all channels active.

Used for testing.

The instrumentation key used for .

An arbitrary API key used for testing. DO NOT use this key in production as it is not valid.

https://www.osgwiki.com/wiki/CommonSchema/flags

Mask for the first byte

an event can be lost due to low bandwidth or disk space constraints

Used for events that should be prioritized over non-critical events. (It is unrelated to retention in Cosmos.)

Mask for the second byte

Default latency

Low latency event. The platform may restrict events that can use this flag

Latency depends on network cost. Functionally treated as "Normal" latency for N days, then becomes "RealTime" latency. The platform may restrict events that can use this flag

Mask for the third byte

Reflects the value of the SQM IsTest registry key

Reflects the value of the SQM MSFTInternal registry key

https://microsoft.sharepoint.com/teams/osg_core_fun/idt/OSGInstrument/SitePages/De-Identification%20of%20Telemetry%20Events.aspx Contains PII. If an event is logged with LogOption.Sensitive using Service Logging Library(SLL), then the flags field will have the IsPII bit turned ON and the event will be considered UserSensitive.

Client has hashed or dropped any PII information in the event. Vortex will hash any server-supplied PII fields such as PUID or Global Device ID

Client has dropped any PII information in the event. Information contained within attached MSA token will not be inserted

See details here.Collector to scrub ext.ingest.clientIp field stamped server-side.This takes precedence over both Hash Identifier and Drop Identifier flags above, so as long as this bit is set, the client IP will be scrubbed as "xxx.xxx.xxx.*" for IPv4 and will not be dropped. The main use case for this flag is Interchange customers that need to use OriginalMessage feature but wish not to have IP info in Geneva data store. For more details on this scenario: 1DS Interchange Default CommonSchema

Used to set the default values used by the method.

Defines a scenario to track, that has a start, an end and duration.

eg. Create, Delete, Load, Update, Execute, etc.

eg. Start, Progress, Complete, Failure, etc.

Represents an in-progress scenario for PPUX shell telemetry schema.

Represent the abstraction of a telemetry client for PPUX Shell telemetry.

Name of the app in the PPUX telemetry clusters. By convension, Power Platform Developer Tool applications use the prefix: "ppdevtools-". data_appName (EventInfo_AppName)

data_appEnvironment (UserInfo_Environment) local, dev, tie, test, preprod, preview, prod, gov, dod, mooncake, ex, rx https://msazure.visualstudio.com/OneAgile/_git/power-platform-ux?path=/packages/build-scripts/src/config/env.interface.ts&version=GBmaster&_a=contents

The default top-level scope to use for all telemetry produced by the app.

The default top-level team to use for all telemetry produced by the app.

Creates a new instance of using the metadata in the given . This assembly is expected to have the applied to it, otherwise, an exception will be thrown.

Generally the entry assembly for the application or unit test assembly. Overrides the value set by the attribute in the assembly. The main usage for this is to allow for testing to override the default behavior.

The normalized value for the PPUX data_appEnvironment property.

e.g."Windows", "Linux"

e.g. "10" (for Windows 10).

The resolution of the current screen. Format: "{width}x{height}"

Wrapper class for all PPUX telemetry data sent via OneDS/OneCollector.

Part C These fields are defined by the Event Author, who has complete control over naming and data type of the fields. The Event Author is responsible for populating these fields when an event is instantiated. https://github.com/microsoft/common-schema/blob/main/README.md Event An actual instantiation of a set of data described by an Event Definition.This is the data that actually gets logged and transmitted over the wire to the Asimov system. An event emitted in response to a significant action or interaction. The data payload of the event describes attributes and semantics about the stimulus that triggered its creation. https://eng.ms/docs/cloud-ai-platform/business-applications-and-platform/bap-power-apps/power-platform-ux/telemetry/powerplatformux/event

Name of the app such as PacCli, PRT, CMT, make-powerapps-com, powerautomate-microsoft-com, ppuxdevcenter. data_appName (EventInfo_AppName)

data_appEnvironment (UserInfo_Environment) tie, test, preprod, preview, prod, gov, high, dod, mooncake, ex, rx https://msazure.visualstudio.com/OneAgile/_git/power-platform-ux?path=/packages/build-scripts/src/config/env.interface.ts&version=GBmaster&_a=contents

Name of the package (or assembly) the log is coming from. Ex: PAC CLI module name, Current Executing Assembly Name data_scope (EventInfo_Scope)

The build name/number.

Name of team owning the event. data_team (EventInfo_Team)

The application display language, in IETF language tag format. eg. `en`.

User's locale. eg. `en-US`, `hi-IN`.

The time the event was logged including local time offset.

UTC time when the event was logged. data_time (EventInfo_Time)

Name of the telemetry event. data_eventName (EventInfo_EventName)

e.g. Trace, Scenario, Custom, etc. data_eventType (EventInfo_Type)

Subtype of the event. For 'Scenario', can be 'Load', 'Execute', etc. data_eventSubtype (EventInfo_Subtype)

GUID representing an identifier of a certain scenario for data_eventType = Scenario This will help to track scenario modifiers such as start/complete. data_scenarioId (EventInfo_ScenarioId)

Scenario Modifier used for data_eventType == Scenario or Custom. Possible values: Failure, Progress, Start, Complete or string. This can be used to calculate SLA. data_eventModifier (EventInfo_Modifier)

data_message (n/a)

LogLevel Possible values: Debug, Information, Warning, Error

data_eventInfo

UUID of an event. Used this to join OutgoingRequest table (data_activityId column)

User's AAD Tenant Id. data_tenantId (UserInfo_TenantId)

User's AAD Object Id. data_principalObjectId (UserInfo_ObjectId)

User's AAD PUID.

Dataverse organization id for the event. data_organizationId (n/a)

Environment id for the event. data_organizationId (n/a)

Error code for the event.

Error name for the event.

Error stack for the event.

Error code for the innermost error.

Error name for the innermost error.

Error stack for the innermost error.

Name of the OS. ex: Windows

Version of the OS.

Properties that are unique to this event being tracked. Any properties here will override properties in . Properties that are unique to this event being tracked. Any properties here will override properties in . Properties that are unique to this event being tracked. Any properties here will override properties in . Properties that are unique to this event being tracked. Any properties here will override properties in .

track Failure

The id of the client session. Defaults to .

Gets the App's 2-letter language name via .

Gets the user locale based on .

Explicit copy ctor to ensure we create a new dictionary instance for the GlobalProperties.

The default scope for all telemetry produced by clients that utilize this context. By default (or whenever this property is set to `null`) the value comes from the property.

The default team for all telemetry produced by clients that utilize this context. By default (or whenever this property is set to `null`) the value comes from the property.

The id of the current activity. All events within the same activity will get this id assigned to help correlate events with the same top-level client activity or operation.

Shared properties that will be added to all events.

Sets the context-owned properites of the event data to the values in this context instance. Most properties are overriden by the explicit values of the context.

data_country: Usually a 2 letter code, seen equally with uppercase and lowercase.

data_userRegion: Usually a 3-4 letter code, lowercase.

Properties that are sent with every event associated with this scenario. Properties that are only sent with the 'start' record for this scenario. Properties that are sent with every event associated with this scenario. Properties that are unique to this event being tracked. Any properties here will override properties in .

When targeting netstandard2.0 and netframework TFMs, many framework APIs do not have the nullable annotations. This causes the compiler to emit warnings for all of these APIs. Callers must then add extra checks in cross-TFM code just to appease the compiler because it thinks a value may be null. This class is a simple wrapper around some of these utilities and adds the nullable annotations.

Each of these methods is a simple wrapper around the corresponding string method. To optimize compiled code, we also hint to the compiler to aggressively inline these methods so to remove any overhead of the wrapper.

Returns a new string in which all occurrences of a specified string in the current instance are replaced with another specified string, using ordinal comparison.

Returns a value indicating whether a specified string occurs within this string, using ordinal comparison.

Initializes a new instance of the System.Diagnostics.CodeAnalysis.NotNullAttribute class.

Initializes the attribute with the specified return value condition.

The return value condition. If the method returns this value, the associated parameter will not be null.

Gets the return value condition.

Specifies that the method will not return if the associated Boolean parameter is passed the specified value.

Initializes the attribute with the specified parameter value.

The condition parameter value. Code after the method will be considered unreachable by diagnostics if the argument to the associated parameter matches this value.

Gets the condition parameter value.

Specifies that the method or property will ensure that the listed field and property members have not-null values.

Initializes the attribute with a field or property member.

The field or property member that is promised to be not-null.

Initializes the attribute with the list of field and property members.

The list of field and property members that are promised to be not-null.

Gets field or property member names.

This class adds members to the String class which are not available in any of the .net frameworks, but are in Core.