Complete API documentation

seq-api.sln.DotSettings

@@ -2,15 +2,27 @@
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=AD/@EntryIndexedValue">AD</s:String>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=apikey/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Datalust/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=donut/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=dstkey/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=ffee/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Gravatar/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=hrefs/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Invalidations/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Iocp/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Parameterize/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=permalinked/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=permalinks/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Permalinks/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Reentrant/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=seqbak/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Seq_0027s/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Serilog/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=srckey/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=strikethrough/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=templated/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=timeseries/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=tokenless/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Unsubscriber/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Uptime/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Workspaces/@EntryIndexedValue">True</s:Boolean>
 </wpf:ResourceDictionary>

src/Seq.Api/Model/AppInstances/AppInstanceEntity.cs

@@ -1,13 +1,37 @@
-using System;
+// Copyright 2014-2019 Datalust and contributors. 
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
 using System.Collections.Generic;
 using Newtonsoft.Json;
 using Seq.Api.Model.Apps;
 using Seq.Api.Model.Signals;
+using Seq.Api.ResourceGroups;
 
 namespace Seq.Api.Model.AppInstances
 {
+    /// <summary>
+    /// App instances are individual processes based on a running <see cref="AppEntity"/> that can
+    /// read from and write to the Seq event stream.
+    /// </summary>
     public class AppInstanceEntity : Entity
     {
+        /// <summary>
+        /// Construct an <see cref="AppInstanceEntity"/> with default values.
+        /// </summary>
+        /// <remarks>Instead of constructing an instance directly, consider using
+        /// <see cref="AppInstancesResourceGroup.TemplateAsync"/> to obtain a partly-initialized instance.</remarks>
         public AppInstanceEntity()
         {
             Settings = new Dictionary<string, string>();
@@ -17,8 +41,19 @@ public AppInstanceEntity()
             Metrics = new AppInstanceMetricsPart();
         }
 
+        /// <summary>
+        /// The id of the <see cref="AppEntity"/> that this is an instance of.
+        /// </summary>
         public string AppId { get; set; }
+
+        /// <summary>
+        /// The user-friendly title of the app instance.
+        /// </summary>
         public string Title { get; set; }
+
+        /// <summary>
+        /// Values for the settings exposed by the app.
+        /// </summary>
         public Dictionary<string, string> Settings { get; set; }
 
         /// <summary>
@@ -32,25 +67,67 @@ public AppInstanceEntity()
         /// as the target for alert notifications.
         /// </summary>
         public bool AcceptDirectInvocation { get; set; }
+
+        /// <summary>
+        /// The settings that can be overridden at invocation time (when an event is sent to
+        /// the instance).
+        /// </summary>
         public List<string> InvocationOverridableSettings { get; set; }
+
+        /// <summary>
+        /// Metadata describing the overridable settings. This field is provided by the server
+        /// and cannot be modified.
+        /// </summary>
         public List<AppSettingPart> InvocationOverridableSettingDefinitions { get; set; }
 
         /// <summary>
-        /// If <c>true</c>, events will be streamed to the app.
+        /// If <c>true</c>, events will be streamed to the app. Otherwise, events will be
+        /// sent only manually or in response to alerts being triggered.
         /// </summary>
         public bool AcceptStreamedEvents { get; set; }
+
+        /// <summary>
+        /// The signal expression describing which events will be sent to the app; if <c>null</c>,
+        /// all events will reach the app.
+        /// </summary>
         public SignalExpressionPart InputSignalExpression { get; set; }
+
+        /// <summary>
+        /// If a value is specified, events will be buffered to disk and sorted by timestamp-order
+        /// within the specified window. This is not recommended for performance reasons, and should
+        /// be avoided when possible.
+        /// </summary>
         public TimeSpan? ArrivalWindow { get; set; }
+
+        /// <summary>
+        /// The time after an event reaches the app during which no further events will be processed.
+        /// The default <see cref="TimeSpan.Zero"/> indicates no suppression time, and all events
+        /// will be processed in that case.
+        /// </summary>
         public TimeSpan SuppressionTime { get; set; }
+
+        /// <summary>
+        /// If <see cref="SuppressionTime"/> is set, the number of events that will be allowed during the
+        /// suppression window. The default is <c>1</c>, to allow only the initial event that triggered suppression.
+        /// </summary>
         public int EventsPerSuppressionWindow { get; set; }
 
+        /// <summary>
+        /// Metrics describing the state and activity of the app.
+        /// </summary>
         [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
         public AppInstanceMetricsPart Metrics { get; set; }
 
+        /// <summary>
+        /// Obsolete.
+        /// </summary>
         [Obsolete("Use !AcceptStreamedEvents instead. This field will be removed in Seq 6.0.")]
         [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
         public bool? IsManualInputOnly { get; set; }
 
+        /// <summary>
+        /// Obsolete.
+        /// </summary>
         [Obsolete("Use !AcceptDirectInvocation instead. This field will be removed in Seq 6.0.")]
         [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
         public bool? DisallowManualInput { get; set; }

src/Seq.Api/Model/AppInstances/AppInstanceMetricsPart.cs

@@ -1,10 +1,43 @@
-namespace Seq.Api.Model.AppInstances
+// Copyright 2014-2019 Datalust and contributors. 
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace Seq.Api.Model.AppInstances
 {
+    /// <summary>
+    /// Metrics describing an <see cref="AppInstanceEntity"/>.
+    /// </summary>
     public class AppInstanceMetricsPart
     {
+        /// <summary>
+        /// The number of events that reached the app in the past minute.
+        /// </summary>
         public int ReceivedEventsPerMinute { get; set; }
+
+        /// <summary>
+        /// The number of diagnostic events raised by the app in the past minute.
+        /// </summary>
+        /// <remarks>This does not include the events received by an input app.</remarks>
         public int EmittedEventsPerMinute { get; set; }
+
+        /// <summary>
+        /// The size, in bytes, of the app process working set.
+        /// </summary>
         public long ProcessWorkingSetBytes { get; set; }
+
+        /// <summary>
+        /// If the app process is running, <c>true</c>; otherwise, <c>false</c>.
+        /// </summary>
         public bool IsRunning { get; set; }
     }
 }

src/Seq.Api/Model/Apps/AppEntity.cs

@@ -1,25 +1,62 @@
-using System;
+// Copyright 2014-2019 Datalust and contributors. 
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using System.Collections.Generic;
-using Newtonsoft.Json;
+using Seq.Api.ResourceGroups;
 
 namespace Seq.Api.Model.Apps
 {
+    /// <summary>
+    /// Seq apps are executable plug-ins that read from and write to the Seq event stream.
+    /// </summary>
     public class AppEntity : Entity
     {
+        /// <summary>
+        /// Construct an <see cref="AppEntity"/> with default values.
+        /// </summary>
+        /// <remarks>Instead of constructing an instance directly, consider using
+        /// <see cref="AppsResourceGroup.TemplateAsync"/> to obtain a partly-initialized instance.</remarks>
         public AppEntity()
         {
             Name = "New App";
             AvailableSettings = new List<AppSettingPart>();
         }
 
+        /// <summary>
+        /// The friendly name of the app.
+        /// </summary>
         public string Name { get; set; }
 
+        /// <summary>
+        /// A long-form description of the app.
+        /// </summary>
         public string Description { get; set; }
 
+        /// <summary>
+        /// Metadata describing the settings exposed by instances of the app.
+        /// </summary>
         public List<AppSettingPart> AvailableSettings { get; set; }
 
+        /// <summary>
+        /// Whether instances of the app can safely process their own diagnostic events. The
+        /// default is <c>false</c>. This option should not normally be set.
+        /// </summary>
         public bool AllowReprocessing { get; set; }
 
+        /// <summary>
+        /// Metadata describing the NuGet package containing the executable app components.
+        /// </summary>
         public AppPackagePart Package { get; set; }
 
         /// <summary>

src/Seq.Api/Model/Apps/AppPackagePart.cs

@@ -1,13 +1,59 @@
-namespace Seq.Api.Model.Apps
+// Copyright 2014-2019 Datalust and contributors. 
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Seq.Api.Model.Feeds;
+
+namespace Seq.Api.Model.Apps
 {
+    /// <summary>
+    /// Describes a NuGet package containing executable app components.
+    /// </summary>
     public class AppPackagePart
     {
+        /// <summary>
+        /// The id of the <see cref="NuGetFeedEntity"/> from which the package was installed.
+        /// </summary>
         public string NuGetFeedId { get; set; }
+
+        /// <summary>
+        /// The package id, for example <c>Seq.Input.HealthCheck</c>.
+        /// </summary>
         public string PackageId { get; set; }
+
+        /// <summary>
+        /// The version of the package.
+        /// </summary>
         public string Version { get; set; }
+
+        /// <summary>
+        /// Package authorship information.
+        /// </summary>
         public string Authors { get; set; }
+
+        /// <summary>
+        /// URL of an icon for the app package.
+        /// </summary>
         public string IconUrl { get; set; }
+
+        /// <summary>
+        /// URL of the package license.
+        /// </summary>
         public string LicenseUrl { get; set; }
+
+        /// <summary>
+        /// Whether an update is known to be available for the app.
+        /// </summary>
         public bool UpdateAvailable { get; set; }
     }
 }

src/Seq.Api/Model/Apps/AppSettingPart.cs

@@ -1,11 +1,50 @@
-namespace Seq.Api.Model.Apps
+// Copyright 2014-2019 Datalust and contributors. 
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace Seq.Api.Model.Apps
 {
+    /// <summary>
+    /// Describes a setting exposed by instances of an <see cref="AppEntity"/>.
+    /// </summary>
     public class AppSettingPart
     {
+        /// <summary>
+        /// The unique name identifying the setting.
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// A friendly, descriptive name of the setting.
+        /// </summary>
         public string DisplayName { get; set; }
+
+        /// <summary>
+        /// Whether the setting is required in order for the app to function.
+        /// </summary>
         public bool IsOptional { get; set; }
+
+        /// <summary>
+        /// Long-form description of the setting.
+        /// </summary>
         public string HelpText { get; set; }
+
+        /// <summary>
+        /// The type of value accepted for the setting; valid values are <c>Text</c>,
+        /// <c>LongText</c>, <c>Checkbox</c>, <c>Integer</c>, <c>Decimal</c>, and <c>Password</c>.
+        /// </summary>
+        /// <remarks>An enum was historically not used here in order to improve
+        /// forwards/backwards compatibility.</remarks>
         public string Type { get; set; }
     }
 }