Add User-Agent string to API calls to Elasticsearch (#3784)

This commit adds a User-Agent to all API calls to Elasticsearch, that includes the client name and version, along with OS, Framework and assembly.

Where System.Runtime.InteropServices.RuntimeInformation is available, use the properties of this type. For .NET 4.6.1 which does not support this type, use native Windows functions to determine the version of Windows, and Environment.OSVersion.VersionString for other platforms. The latter is not used for Windows because it can report incorrect version information depending on runtime version and service packs installed, and the context in which calls are executed i.e. it is not reliable.

Add static readonly strings for default user agents for both the low level and high level clients

Author: russcam

src/Elasticsearch.Net/Configuration/ConnectionConfiguration.cs

@@ -6,63 +6,97 @@
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Net.Security;
+using System.Reflection;
 using System.Security.Cryptography.X509Certificates;
 using System.Threading;
 
 #if DOTNETCORE
 using System.Net.Http;
+using System.Runtime.InteropServices;
 #endif
 
-
 namespace Elasticsearch.Net
 {
 	/// <summary>
-	/// ConnectionConfiguration allows you to control how ElasticLowLevelClient behaves and where/how it connects
-	/// to elasticsearch
+	/// Allows you to control how <see cref="ElasticLowLevelClient"/> behaves and where/how it connects to Elasticsearch
 	/// </summary>
 	public class ConnectionConfiguration : ConnectionConfiguration<ConnectionConfiguration>
 	{
+		/// <summary>
+		/// The default ping timeout. Defaults to 2 seconds
+		/// </summary>
 		public static readonly TimeSpan DefaultPingTimeout = TimeSpan.FromSeconds(2);
+
+		/// <summary>
+		/// The default ping timeout when the connection is over HTTPS. Defaults to
+		/// 5 seconds
+		/// </summary>
 		public static readonly TimeSpan DefaultPingTimeoutOnSSL = TimeSpan.FromSeconds(5);
+
+		/// <summary>
+		/// The default timeout before the client aborts a request to Elasticsearch.
+		/// Defaults to 1 minute
+		/// </summary>
 		public static readonly TimeSpan DefaultTimeout = TimeSpan.FromMinutes(1);
+
+		/// <summary>
+		/// The default connection limit for both Elasticsearch.Net and Nest. Defaults to <c>80</c> except for
+		/// HttpClientHandler implementations based on curl, which defaults to
+		/// <see cref="Environment.ProcessorCount"/>
+		/// </summary>
 		public static readonly int DefaultConnectionLimit = IsCurlHandler ? Environment.ProcessorCount : 80;
 
+		/// <summary>
+		/// The default user agent for Elasticsearch.Net
+		/// </summary>
+		public static readonly string DefaultUserAgent = $"elasticsearch-net/{typeof(IConnectionConfigurationValues).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>().InformationalVersion} ({RuntimeInformation.OSDescription}; {RuntimeInformation.FrameworkDescription}; Elasticsearch.Net)";
 
 		/// <summary>
-		/// ConnectionConfiguration allows you to control how ElasticLowLevelClient behaves and where/how it connects
-		/// to elasticsearch
+		/// Creates a new instance of <see cref="ConnectionConfiguration"/>
 		/// </summary>
-		/// <param name="uri">The root of the elasticsearch node we want to connect to. Defaults to http://localhost:9200</param>
+		/// <param name="uri">The root of the Elasticsearch node we want to connect to. Defaults to http://localhost:9200</param>
 		[SuppressMessage("Microsoft.Reliability", "CA2000:Dispose objects before losing scope")]
 		public ConnectionConfiguration(Uri uri = null)
 			: this(new SingleNodeConnectionPool(uri ?? new Uri("http://localhost:9200"))) { }
 
 		/// <summary>
-		/// ConnectionConfiguration allows you to control how ElasticLowLevelClient behaves and where/how it connects
-		/// to elasticsearch
+		/// Creates a new instance of <see cref="ConnectionConfiguration"/>
 		/// </summary>
-		/// <param name="connectionPool">A connection pool implementation that'll tell the client what nodes are available</param>
+		/// <param name="connectionPool">A connection pool implementation that tells the client what nodes are available</param>
 		public ConnectionConfiguration(IConnectionPool connectionPool)
 			// ReSharper disable once IntroduceOptionalParameters.Global
 			: this(connectionPool, null, null) { }
 
+		/// <summary>
+		/// Creates a new instance of <see cref="ConnectionConfiguration"/>
+		/// </summary>
+		/// <param name="connectionPool">A connection pool implementation that tells the client what nodes are available</param>
+		/// <param name="connection">An connection implementation that can make API requests</param>
 		public ConnectionConfiguration(IConnectionPool connectionPool, IConnection connection)
 			// ReSharper disable once IntroduceOptionalParameters.Global
 			: this(connectionPool, connection, null) { }
 
+		/// <summary>
+		/// Creates a new instance of <see cref="ConnectionConfiguration"/>
+		/// </summary>
+		/// <param name="connectionPool">A connection pool implementation that tells the client what nodes are available</param>
+		/// <param name="serializer">A serializer implementation used to serialize requests and deserialize responses</param>
 		public ConnectionConfiguration(IConnectionPool connectionPool, IElasticsearchSerializer serializer)
 			: this(connectionPool, null, serializer) { }
 
-		// ReSharper disable once MemberCanBePrivate.Global
-		// eventhough we use don't use this we very much would like to  expose this constructor
-
+		/// <summary>
+		/// Creates a new instance of <see cref="ConnectionConfiguration"/>
+		/// </summary>
+		/// <param name="connectionPool">A connection pool implementation that tells the client what nodes are available</param>
+		/// <param name="connection">An connection implementation that can make API requests</param>
+		/// <param name="serializer">A serializer implementation used to serialize requests and deserialize responses</param>
 		public ConnectionConfiguration(IConnectionPool connectionPool, IConnection connection, IElasticsearchSerializer serializer)
 			: base(connectionPool, connection, serializer) { }
 
 		internal static bool IsCurlHandler { get; } =
 #if DOTNETCORE
-                typeof(HttpClientHandler).Assembly.GetType("System.Net.Http.CurlHandler") != null;
-            #else
+			typeof(HttpClientHandler).Assembly.GetType("System.Net.Http.CurlHandler") != null;
+#else
 			false;
 #endif
 	}
@@ -139,6 +173,8 @@ public abstract class ConnectionConfiguration<T> : IConnectionConfigurationValue
 
 		private readonly ElasticsearchUrlFormatter _urlFormatter;
 
+		private string _userAgent = ConnectionConfiguration.DefaultUserAgent;
+
 		protected ConnectionConfiguration(IConnectionPool connectionPool, IConnection connection, IElasticsearchSerializer requestResponseSerializer)
 		{
 			_connectionPool = connectionPool;
@@ -198,6 +234,7 @@ protected ConnectionConfiguration(IConnectionPool connectionPool, IConnection co
 		bool IConnectionConfigurationValues.SniffsOnStartup => _sniffOnStartup;
 		bool IConnectionConfigurationValues.ThrowExceptions => _throwExceptions;
 		ElasticsearchUrlFormatter IConnectionConfigurationValues.UrlFormatter => _urlFormatter;
+		string IConnectionConfigurationValues.UserAgent => _userAgent;
 
 		void IDisposable.Dispose() => DisposeManagedResources();
 
@@ -500,6 +537,12 @@ public T ClientCertificate(string certificatePath) =>
 		public T SkipDeserializationForStatusCodes(params int[] statusCodes) =>
 			Assign(new ReadOnlyCollection<int>(statusCodes), (a, v) => a._skipDeserializationForStatusCodes = v);
 
+		/// <summary>
+		/// The user agent string to send with requests. Useful for debugging purposes to understand client and framework
+		/// versions that initiate requests to Elasticsearch
+		/// </summary>
+		public T UserAgent(string userAgent) => Assign(userAgent, (a, v) => a._userAgent = v);
+
 		protected virtual void DisposeManagedResources()
 		{
 			_connectionPool?.Dispose();

src/Elasticsearch.Net/Configuration/IConnectionConfigurationValues.cs

@@ -213,5 +213,11 @@ public interface IConnectionConfigurationValues : IDisposable
 		bool ThrowExceptions { get; }
 
 		ElasticsearchUrlFormatter UrlFormatter { get; }
+
+		/// <summary>
+		/// The user agent string to send with requests. Useful for debugging purposes to understand client and framework
+		/// versions that initiate requests to Elasticsearch
+		/// </summary>
+		string UserAgent { get; }
 	}
 }

src/Elasticsearch.Net/Connection/HttpConnection-CoreFx.cs

@@ -222,6 +222,12 @@ protected virtual HttpRequestMessage CreateRequestMessage(RequestData requestDat
 			requestMessage.Headers.ConnectionClose = false;
 			requestMessage.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue(requestData.Accept));
 
+			if (!string.IsNullOrWhiteSpace(requestData.UserAgent))
+			{
+				requestMessage.Headers.UserAgent.Clear();
+				requestMessage.Headers.UserAgent.TryParseAdd(requestData.UserAgent);
+			}
+
 			if (!requestData.RunAs.IsNullOrEmpty())
 				requestMessage.Headers.Add(RequestData.RunAsSecurityHeader, requestData.RunAs);
 

src/Elasticsearch.Net/Connection/HttpWebRequestConnection.cs

@@ -185,6 +185,10 @@ protected virtual HttpWebRequest CreateWebRequest(RequestData requestData)
 				request.Headers.Add("Accept-Encoding", "gzip,deflate");
 				request.Headers.Add("Content-Encoding", "gzip");
 			}
+
+			if (!string.IsNullOrWhiteSpace(requestData.UserAgent))
+				request.UserAgent = requestData.UserAgent;
+
 			if (!string.IsNullOrWhiteSpace(requestData.RunAs))
 				request.Headers.Add(RequestData.RunAsSecurityHeader, requestData.RunAs);
 

src/Elasticsearch.Net/Domain/NativeMethods.cs

@@ -0,0 +1,42 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+// https://raw.githubusercontent.com/dotnet/core-setup/master/src/managed/Microsoft.DotNet.PlatformAbstractions/Native/NativeMethods.Windows.cs
+
+using System.Runtime.InteropServices;
+
+namespace Elasticsearch.Net
+{
+	internal static class NativeMethods
+	{
+		public static class Windows
+		{
+			// This call avoids the shimming Windows does to report old versions
+			[DllImport("ntdll")]
+			private static extern int RtlGetVersion(out RTL_OSVERSIONINFOEX lpVersionInformation);
+
+			internal static string RtlGetVersion()
+			{
+				var osvi = new RTL_OSVERSIONINFOEX();
+				osvi.dwOSVersionInfoSize = (uint)Marshal.SizeOf(osvi);
+				if (RtlGetVersion(out osvi) == 0)
+					return $"Microsoft Windows {osvi.dwMajorVersion}.{osvi.dwMinorVersion}.{osvi.dwBuildNumber}";
+
+				return null;
+			}
+
+			[StructLayout(LayoutKind.Sequential)]
+			internal struct RTL_OSVERSIONINFOEX
+			{
+				internal uint dwOSVersionInfoSize;
+				internal uint dwMajorVersion;
+				internal uint dwMinorVersion;
+				internal uint dwBuildNumber;
+				internal uint dwPlatformId;
+
+				[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)]
+				internal string szCSDVersion;
+			}
+		}
+	}
+}

src/Elasticsearch.Net/Domain/RuntimeInformation.cs

@@ -0,0 +1,44 @@
+using System;
+#if NET461
+using System.Reflection;
+
+namespace Elasticsearch.Net
+{
+	internal static class RuntimeInformation
+	{
+		private static string _frameworkDescription;
+		private static string _osDescription;
+
+		public static string FrameworkDescription
+		{
+			get
+			{
+				if (_frameworkDescription == null)
+				{
+					var assemblyFileVersionAttribute =
+						(AssemblyFileVersionAttribute)typeof(object).GetTypeInfo().Assembly.GetCustomAttribute(typeof(AssemblyFileVersionAttribute));
+					_frameworkDescription = $".NET Framework {assemblyFileVersionAttribute.Version}";
+				}
+				return _frameworkDescription;
+			}
+		}
+
+		public static string OSDescription
+		{
+			get
+			{
+				if (_osDescription == null)
+				{
+					var platform = (int)Environment.OSVersion.Platform;
+					var isWindows = platform != 4 && platform != 6 && platform != 128;
+					if (isWindows)
+						_osDescription = NativeMethods.Windows.RtlGetVersion() ?? "Microsoft Windows";
+					else
+						_osDescription = Environment.OSVersion.VersionString;
+				}
+				return _osDescription;
+			}
+		}
+	}
+}
+#endif

src/Elasticsearch.Net/Transport/Pipeline/RequestData.cs

@@ -67,6 +67,7 @@ IMemoryStreamFactory memoryStreamFactory
 			BasicAuthorizationCredentials = local?.BasicAuthenticationCredentials ?? global.BasicAuthenticationCredentials;
 			AllowedStatusCodes = local?.AllowedStatusCodes ?? Enumerable.Empty<int>();
 			ClientCertificates = local?.ClientCertificates ?? global.ClientCertificates;
+			UserAgent = global.UserAgent;
 		}
 
 		public string Accept { get; }
@@ -104,6 +105,7 @@ IMemoryStreamFactory memoryStreamFactory
 		public string RunAs { get; }
 		public IReadOnlyCollection<int> SkipDeserializationForStatusCodes { get; }
 		public bool ThrowExceptions { get; }
+		public string UserAgent { get; }
 
 		public Uri Uri => Node != null ? new Uri(Node.Uri, PathAndQuery) : null;
 

src/Nest/CommonAbstractions/ConnectionSettings/ConnectionSettingsBase.cs

@@ -6,11 +6,21 @@
 using System.Reflection;
 using Elasticsearch.Net;
 
+#if DOTNETCORE
+using System.Runtime.InteropServices;
+#endif
+
 namespace Nest
 {
 	/// <inheritdoc cref="IConnectionSettingsValues" />
 	public class ConnectionSettings : ConnectionSettingsBase<ConnectionSettings>
 	{
+		/// <summary>
+		/// The default user agent for Nest
+		/// </summary>
+		public static readonly string DefaultUserAgent =
+			$"elasticsearch-net/{typeof(IConnectionSettingsValues).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>().InformationalVersion} ({RuntimeInformation.OSDescription}; {RuntimeInformation.FrameworkDescription}; Nest)";
+
 		/// <summary>
 		/// A delegate used to construct a serializer to serialize CLR types representing documents and other types related to documents.
 		/// By default, the internal serializer will be used to serializer all types.
@@ -101,6 +111,8 @@ IPropertyMappingProvider propertyMappingProvider
 			_defaultRelationNames = new FluentDictionary<Type, string>();
 
 			_inferrer = new Inferrer(this);
+
+			UserAgent(ConnectionSettings.DefaultUserAgent);
 		}
 
 		Func<string, string> IConnectionSettingsValues.DefaultFieldNameInferrer => _defaultFieldNameInferrer;

src/Nest/CrossPlatform/NativeMethods.cs

@@ -0,0 +1,42 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+// https://raw.githubusercontent.com/dotnet/core-setup/master/src/managed/Microsoft.DotNet.PlatformAbstractions/Native/NativeMethods.Windows.cs
+
+using System.Runtime.InteropServices;
+
+namespace Nest
+{
+	internal static class NativeMethods
+	{
+		public static class Windows
+		{
+			// This call avoids the shimming Windows does to report old versions
+			[DllImport("ntdll")]
+			private static extern int RtlGetVersion(out RTL_OSVERSIONINFOEX lpVersionInformation);
+
+			internal static string RtlGetVersion()
+			{
+				var osvi = new RTL_OSVERSIONINFOEX();
+				osvi.dwOSVersionInfoSize = (uint)Marshal.SizeOf(osvi);
+				if (RtlGetVersion(out osvi) == 0)
+					return $"Microsoft Windows {osvi.dwMajorVersion}.{osvi.dwMinorVersion}.{osvi.dwBuildNumber}";
+
+				return null;
+			}
+
+			[StructLayout(LayoutKind.Sequential)]
+			internal struct RTL_OSVERSIONINFOEX
+			{
+				internal uint dwOSVersionInfoSize;
+				internal uint dwMajorVersion;
+				internal uint dwMinorVersion;
+				internal uint dwBuildNumber;
+				internal uint dwPlatformId;
+
+				[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)]
+				internal string szCSDVersion;
+			}
+		}
+	}
+}