public endpoint schema

Author: Sergey Kanzhelev

.gitignore

@@ -68,9 +68,14 @@ Ankh.NoLoad
 
 # Ignore NuGet packages.
 /NuGet.Packages/*
+# Enable "build/" folder in the NuGet Packages folder since NuGet packages use it for MSBuild targets
+!packages/*/build/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
 
 # Ignore certain directories
-/TestResults/*
 /Samples/AzureEmailService/AzureEmailService/bin/*
 /Samples/AzureEmailService/AzureEmailService/MvcWebRoleContent/*
 /Samples/AzureEmailService/AzureEmailService/obj/*

ENDPOINT-PROTOCOL.md EndpointSpecs/ENDPOINT-PROTOCOL.md

@@ -0,0 +1,11 @@
+
+namespace AI
+
+[Description("Data struct to contain only C section with custom fields.")]
+struct Base
+{
+    [Name("ItemTypeName")]
+    [Description("Name of item (B section) if any. If telemetry data is derived straight from this, this should be null.")]
+    10: string 	 baseType;
+    
+}

SDK-AUTHORING.md EndpointSpecs/SDK-AUTHORING.md

@@ -0,0 +1,100 @@
+
+namespace AI
+
+[ContextContract("Emit")]
+[PseudoType("JSMap")]
+struct ContextTagKeys
+{
+    [Description("Application version. Information in the application context fields is always about the application that is sending the telemetry.")]
+    [MaxStringLength("1024")]
+    10: string 	 ApplicationVersion = "ai.application.ver";
+    
+    [Description("Unique client device id. Computer name in most cases.")]
+    [MaxStringLength("1024")]
+    100: string 	 DeviceId = "ai.device.id";
+    
+    [Description("Device locale using <language>-<REGION> pattern, following RFC 5646. Example 'en-US'.")]
+    [MaxStringLength("64")]
+    115: string 	 DeviceLocale = "ai.device.locale";
+    
+    [Description("Model of the device end user of the application using. Used for client scenarios. If empty, derived from user agent.")]
+    [MaxStringLength("256")]
+    120: string 	 DeviceModel = "ai.device.model";
+    
+    [MaxStringLength("256")]
+    130: string 	 DeviceOEMName = "ai.device.oemName";
+    
+    [Description("Operation system name and version of the device end user of the application using. If empty derived from user agent. Example 'Windows 10 Pro 10.0.10586.0'")]
+    [MaxStringLength("256")]
+    140: string 	 DeviceOSVersion = "ai.device.osVersion";
+    
+    [Description("Type of the device end user of the application is using. Used primarily to distinguish JavaScript telemetry from server side telemetry. Examples: 'PC', 'Phone', 'Browser'. 'PC' is a default value.")]
+    [MaxStringLength("64")]
+    160: string 	 DeviceType = "ai.device.type";
+    
+    [Description("The IPv4 IP address of the client device. IPv6 is not currently supported. Information in the location context fields is always about the end user. When telemetry is sent from a service, the location context is about the user that initiated the operation in the service.")]
+    [MaxStringLength("45")]
+    200: string 	 LocationIp = "ai.location.ip";
+    
+    [Description("A unique identifier for the operation instance. The operation.id is created by either a request or a page view. All other telemetry sets this to the value for the containing request or page view. Operation.id is used for finding all the telemetry items for a specific operation instance.")]
+    [MaxStringLength("128")]
+    300: string 	 OperationId = "ai.operation.id";
+    
+    [Description("The name (group) of the operation. The operation.name is created by either a request or a page view. All other telemetry items set this to the value for the containing request or page view. Operation.name is used for finding all the telemetry items for a group of operations (i.e. 'GET Home/Index').")]
+    [MaxStringLength("1024")]
+    305: string 	 OperationName = "ai.operation.name";
+    
+    [Description("The unique identifier of the telemetry item's immediate parent.")]
+    [MaxStringLength("128")]
+    310: string 	 OperationParentId = "ai.operation.parentId";
+    
+    [Description("Name of synthetic source. Some telemetry from the application may represent a synthetic traffic. It may be web crawler indexing the web site, site availability tests or traces from diagnostic libraries like Application Insights SDK itself.")]
+    [MaxStringLength("1024")]
+    320: string 	 OperationSyntheticSource = "ai.operation.syntheticSource";
+    
+    [Description("The cV is a light weight vector clock which can be used to identify and order related events across clients and services.")]
+    [MaxStringLength("64")]
+    330: string 	 OperationCorrelationVector = "ai.operation.correlationVector";
+    
+    [Description("Session ID - the instance of the user's interaction with the app. Information in the session context fields is always about the end user. When telemetry is sent from a service, the session context is about the user that initiated the operation in the service.")]
+    [MaxStringLength("64")]
+    400: string 	 SessionId = "ai.session.id";
+    
+    [Description("Boolean value indicating whether the session identified by ai.session.id is first for the user or not.")]
+    [MaxStringLength("5")]
+    [Question("Should it be marked as JSType-bool for breeze?")]
+    405: string 	 SessionIsFirst = "ai.session.isFirst";
+    
+    [Description("In multi-tenant applications account ID or name that user is acting with. Examples may be subscription ID for Azure portal or blog name blogging platform.")]
+    [MaxStringLength("1024")]
+    505: string 	 UserAccountId = "ai.user.accountId";
+    
+    [Description("The browser's user agent string as reported by the browser. This property will be used to extract informaiton regarding customer browser, but will not be stored. Use custom properties to store the original user agent.")]
+    [MaxStringLength("2048")]
+    510: string 	 UserAgent = "ai.user.userAgent";
+    
+    [Description("Anonymous user id. Represents the end user of the application. When telemetry is sent from a service, the user context is about the user than initiated the operation in the service.")]
+    [MaxStringLength("128")]
+    515: string 	 UserId = "ai.user.id";
+    
+    [Description("Authenticated user id. As opposite to ai.user.id represents the user with by the friendly name. Since it's PII information it is not collected by default by most SDKs.")]
+    [MaxStringLength("1024")]
+    525: string 	 UserAuthUserId = "ai.user.authUserId";
+    
+    [Description("Name of the role application is part of. Maps directly to the role name in azure.")]
+    [MaxStringLength("256")]
+    705: string 	 CloudRole = "ai.cloud.role";
+    
+    [Description("Name of the instance where application is running. Computer name for on-premisis, instance name for Azure.")]
+    [MaxStringLength("256")]
+    715: string 	 CloudRoleInstance = "ai.cloud.roleInstance";
+    
+    [Description("SDK version. See https://github.com/Microsoft/ApplicationInsights-Home/blob/master/SDK-AUTHORING.md#sdk-version-specification for information.")]
+    [MaxStringLength("64")]
+    1000: string 	 InternalSdkVersion = "ai.internal.sdkVersion";
+    
+    [Description("Agent version. Used to indicate the version of StatusMonitor installed on the computer if it is used for data collection.")]
+    [MaxStringLength("64")]
+    1001: string 	 InternalAgentVersion = "ai.internal.agentVersion";
+    
+}

EndpointSpecs/Schemas/Bond/Base.bond

@@ -0,0 +1,13 @@
+import "Base.bond"
+
+namespace AI
+
+[Description("Data struct to contain both B and C sections.")]
+struct Data<TDomain>
+    : Base
+{
+    [Name("Item")]
+    [Description("Container for data item (B section).")]
+    20: required TDomain 	 baseData;
+    
+}

EndpointSpecs/Schemas/Bond/ContextTagKeys.bond

@@ -0,0 +1,30 @@
+import "DataPointType.bond"
+
+namespace AI
+
+[Description("Metric data single measurement.")]
+struct DataPoint
+{
+    [Description("Name of the metric.")]
+    [MaxStringLength("1024")]
+    10: required string 	 name;
+    
+    [Description("Metric type.")]
+    20: AI.DataPointType 	 kind = Measurement;
+    
+    [Description("Metric calculated value.")]
+    30: required double 	 value;
+    
+    [Description("Metric weight of the aggregated metric. Should not be set for a measurement.")]
+    40: nullable<int32> 	 count;
+    
+    [Description("Minimum value of the aggregated metric. Should not be set for a measurement.")]
+    50: nullable<double> 	 min;
+    
+    [Description("Maximum value of the aggregated metric. Should not be set for a measurement.")]
+    60: nullable<double> 	 max;
+    
+    [Description("Standard deviation of the aggregated metric. Should not be set for a measurement.")]
+    70: nullable<double> 	 stdDev;
+    
+}

EndpointSpecs/Schemas/Bond/Data.bond

@@ -0,0 +1,8 @@
+namespace AI
+
+[Description("Type of the metric data measurement.")]
+enum DataPointType
+{
+    Measurement,
+    Aggregation,
+}

EndpointSpecs/Schemas/Bond/DataPoint.bond

@@ -0,0 +1,7 @@
+
+namespace AI
+
+[Description("The abstract common base of all domains.")]
+struct Domain
+{
+}

EndpointSpecs/Schemas/Bond/DataPointType.bond

@@ -0,0 +1,49 @@
+import "Base.bond"
+
+namespace AI
+
+[Description("System variables for a telemetry item.")]
+struct Envelope
+{
+    [Description("Envelope version. For internal use only. By assigning this the default, it will not be serialized within the payload unless changed to a value other than #1.")]
+    [Name("SchemaVersion")]
+    10: int32 	 ver = 1;
+    
+    [Description("Type name of telemetry data item.")]
+    [Name("DataTypeName")]
+    [MaxStringLength("1024")]
+    20: required string 	 name;
+    
+    [Description("Event date time when telemetry item was created. This is the wall clock time on the client when the event was generated. There is no guarantee that the client's time is accurate. This field must be formatted in UTC ISO 8601 format, with a trailing 'Z' character, as described publicly on https://en.wikipedia.org/wiki/ISO_8601#UTC. Note: the number of decimal seconds digits provided are variable (and unspecified). Consumers should handle this, i.e. managed code consumers should not use format 'O' for parsing as it specifies a fixed length. Example: 2009-06-15T13:45:30.0000000Z.")]
+    [Name("DateTime")]
+    [CSType("DateTimeOffset")]
+    [JSType("Date")]
+    [HockeyAppMinDateOffsetFromNow("2592000000")]
+    [MinDateOffsetFromNow("172800000")]
+    [MaxDateOffsetFromNow("7200000")]
+    30: required string 	 time;
+    
+    [Name("SamplingRate")]
+    [Description("Sampling rate used in application. This telemetry item represents 1 / sampleRate actual telemetry item.")]
+    40: double 	 sampleRate = 100.0;
+    
+    [Description("Sequence field used to track absolute order of uploaded events.")]
+    [Name("SequenceNumber")]
+    [MaxStringLength("64")]
+    50: string 	 seq;
+    
+    [Description("The application's instrumentation key.")]
+    [Name("InstrumentationKey")]
+    [MaxStringLength("40")]
+    60: string 	 iKey;
+    
+    [Name("Tags")]
+    [TypeAlias("ContextTagKeys")]
+    [Description("Key/value collection of context properties. See ContextTagKeys for information on available properties.")]
+    500: map<string, string> 	 tags;
+    
+    [Name("TelemetryData")]
+    [Description("Telemetry data item.")]
+    999: Base 	 data;
+    
+}

EndpointSpecs/Schemas/Bond/Domain.bond

@@ -0,0 +1,26 @@
+import "Domain.bond"
+
+namespace AI
+
+[Description("Instances of Event represent structured event records that can be grouped and searched by their properties. Event data item also creates a metric of event count by name.")]
+struct EventData
+    : Domain
+{
+    [Description("Schema version")]
+    10: required int32 	 ver = 2;
+    
+    [MaxStringLength("512")]
+    [Description("Event name. Keep it low cardinality to allow proper grouping and useful metrics.")]
+    [Question("Why Custom Event name is shorter than Request name or dependency name?")]
+    20: required string 	 name;
+    
+    [Description("Collection of custom properties.")]
+    [MaxKeyLength("150")]
+    [MaxValueLength("8192")]
+    100: map<string, string> 	 properties;
+    
+    [Description("Collection of custom measurements.")]
+    [MaxKeyLength("150")]
+    200: map<string, double> 	 measurements;
+    
+}

EndpointSpecs/Schemas/Bond/Envelope.bond

@@ -0,0 +1,33 @@
+import "Domain.bond"
+import "ExceptionDetails.bond"
+import "SeverityLevel.bond"
+
+namespace AI
+
+[Description("Instance of Exception represents handled or unhandled exception that occurred during execution of the monitored application.")]
+struct ExceptionData
+    : Domain
+{
+    [Description("Schema version")]
+    10: required int32 	 ver = 2;
+    
+    [Description("Exception chain - list of inner exceptions.")]
+    50: required vector<ExceptionDetails> 	 exceptions;
+    
+    [Description("Severity level. Mostly used to indicate exception severity level when it is reported by logging library.")]
+    60: nullable<AI.SeverityLevel> 	 severityLevel;
+    
+    [Description("Identifier of where the exception was thrown in code. Used for exceptions grouping. Typically a combination of exception type and a function from the call stack.")]
+    [MaxStringLength("1024")]
+    80: string 	 problemId;
+    
+    [Description("Collection of custom properties.")]
+    [MaxKeyLength("150")]
+    [MaxValueLength("8192")]
+    100: map<string, string> 	 properties;
+    
+    [Description("Collection of custom measurements.")]
+    [MaxKeyLength("150")]
+    200: map<string, double> 	 measurements;
+    
+}

EndpointSpecs/Schemas/Bond/EventData.bond

@@ -0,0 +1,32 @@
+import "StackFrame.bond"
+
+namespace AI
+
+[Description("Exception details of the exception in a chain.")]
+struct ExceptionDetails
+{
+    [Description("In case exception is nested (outer exception contains inner one), the id and outerId properties are used to represent the nesting.")]
+    10: int32 	 id;
+    
+    [Description("The value of outerId is a reference to an element in ExceptionDetails that represents the outer exception")]
+    20: int32 	 outerId;
+    
+    [Description("Exception type name.")]
+    [MaxStringLength("1024")]
+    30: required string 	 typeName;
+    
+    [Description("Exception message.")]
+    [MaxStringLength("1024")]
+    40: required string 	 message;
+    
+    [Description("Indicates if full exception stack is provided in the exception. Stack may be trimmed, such as in the case of StackOverflow exception.")]
+    50: bool 	 hasFullStack = true;
+    
+    [Description("Text describing the stack. Either stack or parsedStack should have a value.")]
+    [MaxStringLength("32768")]
+    60: string 	 stack;
+    
+    [Description("List of stack frames. Either stack or parsedStack should have a value.")]
+    70: vector<StackFrame> 	 parsedStack;
+    
+}

EndpointSpecs/Schemas/Bond/ExceptionData.bond

@@ -0,0 +1,25 @@
+import "Domain.bond"
+import "SeverityLevel.bond"
+
+namespace AI
+
+[Description("Instances of Message represent printf-like trace statements that are text-searched. Log4Net, NLog and other text-based log file entries are be translated into intances of this type. The message does not have measurements.")]
+struct MessageData
+    : Domain
+{
+    [Description("Schema version")]
+    10: required int32 	 ver = 2;
+    
+    [MaxStringLength("32768")]
+    [Description("Trace message")]
+    20: required string 	 message;
+    
+    [Description("Trace severity level.")]
+    30: nullable<AI.SeverityLevel> 	 severityLevel;
+    
+    [Description("Collection of custom properties.")]
+    [MaxKeyLength("150")]
+    [MaxValueLength("8192")]
+    100: map<string, string> 	 properties;
+    
+}

EndpointSpecs/Schemas/Bond/ExceptionDetails.bond

@@ -0,0 +1,21 @@
+import "Domain.bond"
+import "DataPoint.bond"
+
+namespace AI
+
+[Description("Instance of the Metric item is a list of measurements (single data points) and/or aggregations")]
+struct MetricData
+    : Domain
+{
+    [Description("Schema version")]
+    10: required int32 	 ver = 2;
+    
+    [Description("List of metrics.")]
+    20: required vector<DataPoint> 	 metrics;
+    
+    [Description("Collection of custom properties.")]
+    [MaxKeyLength("150")]
+    [MaxValueLength("8192")]
+    100: map<string, string> 	 properties;
+    
+}