Skip to content

Commit 7bde0e4

Browse files
authored
Merge pull request #8490 from marciw/mw-ts-move
[Docs] Restore troubleshooting content
2 parents 5f46672 + c9b0d62 commit 7bde0e4

12 files changed

+593
-1
lines changed
Loading
Loading
Loading

docs/reference/toc.yml

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,15 @@ toc:
2020
- file: query.md
2121
- file: recommendations.md
2222
- file: transport.md
23-
- file: migration-guide.md
23+
- file: migration-guide.md
24+
- file: troubleshoot/index.md
25+
children:
26+
- file: troubleshoot/logging.md
27+
children:
28+
- file: troubleshoot/logging-with-onrequestcompleted.md
29+
- file: troubleshoot/logging-with-fiddler.md
30+
- file: troubleshoot/debugging.md
31+
children:
32+
- file: troubleshoot/audit-trail.md
33+
- file: troubleshoot/debug-information.md
34+
- file: troubleshoot/debug-mode.md
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/audit-trail.html
4+
---
5+
6+
# Audit trail [audit-trail]
7+
8+
Elasticsearch.Net and NEST provide an audit trail for the events within the request pipeline that occur when a request is made. This audit trail is available on the response as demonstrated in the following example.
9+
10+
We’ll use a Sniffing connection pool here since it sniffs on startup and pings before first usage, so we can get an audit trail with a few events out
11+
12+
```csharp
13+
var pool = new SniffingConnectionPool(new []{ TestConnectionSettings.CreateUri() });
14+
var connectionSettings = new ConnectionSettings(pool)
15+
.DefaultMappingFor<Project>(i => i
16+
.IndexName("project")
17+
);
18+
19+
var client = new ElasticClient(connectionSettings);
20+
```
21+
22+
After issuing the following request
23+
24+
```csharp
25+
var response = client.Search<Project>(s => s
26+
.MatchAll()
27+
);
28+
```
29+
30+
The audit trail is provided in the [Debug information](debug-information.md) in a human readable fashion, similar to
31+
32+
```
33+
Valid NEST response built from a successful low level call on POST: /project/doc/_search
34+
# Audit trail of this API call:
35+
- [1] SniffOnStartup: Took: 00:00:00.0360264
36+
- [2] SniffSuccess: Node: http://localhost:9200/ Took: 00:00:00.0310228
37+
- [3] PingSuccess: Node: http://127.0.0.1:9200/ Took: 00:00:00.0115074
38+
- [4] HealthyResponse: Node: http://127.0.0.1:9200/ Took: 00:00:00.1477640
39+
# Request:
40+
<Request stream not captured or already read to completion by serializer. Set DisableDirectStreaming() on ConnectionSettings to force it to be set on the response.>
41+
# Response:
42+
<Response stream not captured or already read to completion by serializer. Set DisableDirectStreaming() on ConnectionSettings to force it to be set on the response.>
43+
```
44+
to help with troubleshootin
45+
46+
```csharp
47+
var debug = response.DebugInformation;
48+
```
49+
50+
But can also be accessed manually:
51+
52+
```csharp
53+
response.ApiCall.AuditTrail.Count.Should().Be(4, "{0}", debug);
54+
response.ApiCall.AuditTrail[0].Event.Should().Be(SniffOnStartup, "{0}", debug);
55+
response.ApiCall.AuditTrail[1].Event.Should().Be(SniffSuccess, "{0}", debug);
56+
response.ApiCall.AuditTrail[2].Event.Should().Be(PingSuccess, "{0}", debug);
57+
response.ApiCall.AuditTrail[3].Event.Should().Be(HealthyResponse, "{0}", debug);
58+
```
59+
60+
Each audit has a started and ended `DateTime` on it that will provide some understanding of how long it took
61+
62+
```csharp
63+
response.ApiCall.AuditTrail
64+
.Should().OnlyContain(a => a.Ended - a.Started >= TimeSpan.Zero);
65+
```
66+
Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/debug-information.html
4+
---
5+
6+
# Debug information [debug-information]
7+
8+
Every response from Elasticsearch.Net and NEST contains a `DebugInformation` property that provides a human readable description of what happened during the request for both successful and failed requests
9+
10+
```csharp
11+
var response = client.Search<Project>(s => s
12+
.Query(q => q
13+
.MatchAll()
14+
)
15+
);
16+
17+
response.DebugInformation.Should().Contain("Valid NEST response");
18+
```
19+
20+
This can be useful in tracking down numerous problems and can also be useful when filing an [issue](https://github.com/elastic/elasticsearch-net/issues) on the GitHub repository.
21+
22+
## Request and response bytes [_request_and_response_bytes]
23+
24+
By default, the request and response bytes are not available within the debug information, but can be enabled globally on Connection Settings by setting `DisableDirectStreaming`. This disables direct streaming of
25+
26+
1. the serialized request type to the request stream
27+
2. the response stream to a deserialized response type
28+
29+
```csharp
30+
var connectionPool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
31+
32+
var settings = new ConnectionSettings(connectionPool)
33+
.DisableDirectStreaming(); <1>
34+
35+
var client = new ElasticClient(settings);
36+
```
37+
38+
1. disable direct streaming for **all** requests
39+
40+
41+
or on a *per request* basis
42+
43+
```csharp
44+
var response = client.Search<Project>(s => s
45+
.RequestConfiguration(r => r
46+
.DisableDirectStreaming() <1>
47+
)
48+
.Query(q => q
49+
.MatchAll()
50+
)
51+
);
52+
```
53+
54+
1. disable direct streaming for **this** request only
55+
56+
57+
Configuring `DisableDirectStreaming` on an individual request takes precedence over any global configuration.
58+
59+
There is typically a performance and allocation cost associated with disabling direct streaming since both the request and response bytes must be buffered in memory, to allow them to be exposed on the response call details.
60+
61+
62+
## TCP statistics [_tcp_statistics]
63+
64+
It can often be useful to see the statistics for active TCP connections, particularly when trying to diagnose issues with the client. The client can collect the states of active TCP connections just before making a request, and expose these on the response and in the debug information.
65+
66+
Similarly to `DisableDirectStreaming`, TCP statistics can be collected for every request by configuring on `ConnectionSettings`
67+
68+
```csharp
69+
var connectionPool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
70+
71+
var settings = new ConnectionSettings(connectionPool)
72+
.EnableTcpStats(); <1>
73+
74+
var client = new ElasticClient(settings);
75+
```
76+
77+
1. collect TCP statistics for **all** requests
78+
79+
80+
or on a *per request* basis
81+
82+
```csharp
83+
var response = client.Search<Project>(s => s
84+
.RequestConfiguration(r => r
85+
.EnableTcpStats() <1>
86+
)
87+
.Query(q => q
88+
.MatchAll()
89+
)
90+
);
91+
92+
var debugInformation = response.DebugInformation;
93+
```
94+
95+
1. collect TCP statistics for **this** request only
96+
97+
98+
With `EnableTcpStats` set, the states of active TCP connections will now be included on the response and in the debug information.
99+
100+
The client includes a `TcpStats` class to help with retrieving more detail about active TCP connections should it be required
101+
102+
```csharp
103+
var tcpStatistics = TcpStats.GetActiveTcpConnections(); <1>
104+
var ipv4Stats = TcpStats.GetTcpStatistics(NetworkInterfaceComponent.IPv4); <2>
105+
var ipv6Stats = TcpStats.GetTcpStatistics(NetworkInterfaceComponent.IPv6); <3>
106+
107+
var response = client.Search<Project>(s => s
108+
.Query(q => q
109+
.MatchAll()
110+
)
111+
);
112+
```
113+
114+
1. Retrieve details about active TCP connections, including local and remote addresses and ports
115+
2. Retrieve statistics about IPv4
116+
3. Retrieve statistics about IPv6
117+
118+
119+
::::{note}
120+
Collecting TCP statistics may not be accessible in all environments, for example, Azure App Services. When this is the case, `TcpStats.GetActiveTcpConnections()` returns `null`.
121+
122+
::::
123+
124+
125+
126+
## ThreadPool statistics [_threadpool_statistics]
127+
128+
It can often be useful to see the statistics for thread pool threads, particularly when trying to diagnose issues with the client. The client can collect statistics for both worker threads and asynchronous I/O threads, and expose these on the response and in debug information.
129+
130+
Similar to collecting TCP statistics, ThreadPool statistics can be collected for all requests by configuring `EnableThreadPoolStats` on `ConnectionSettings`
131+
132+
```csharp
133+
var connectionPool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
134+
135+
var settings = new ConnectionSettings(connectionPool)
136+
.EnableThreadPoolStats(); <1>
137+
138+
var client = new ElasticClient(settings);
139+
```
140+
141+
1. collect thread pool statistics for **all** requests
142+
143+
144+
or on a *per request* basis
145+
146+
```csharp
147+
var response = client.Search<Project>(s => s
148+
.RequestConfiguration(r => r
149+
.EnableThreadPoolStats() <1>
150+
)
151+
.Query(q => q
152+
.MatchAll()
153+
)
154+
);
155+
156+
var debugInformation = response.DebugInformation; <2>
157+
```
158+
159+
1. collect thread pool statistics for **this** request only
160+
2. contains thread pool statistics
161+
162+
163+
With `EnableThreadPoolStats` set, the statistics of thread pool threads will now be included on the response and in the debug information.
164+
165+
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/debug-mode.html
4+
---
5+
6+
# Debug mode [debug-mode]
7+
8+
The [Debug information](debug-information.md) explains that every response from Elasticsearch.Net and NEST contains a `DebugInformation` property, and properties on `ConnectionSettings` and `RequestConfiguration` can control which additional information is included in debug information, for all requests or on a per request basis, respectively.
9+
10+
During development, it can be useful to enable the most verbose debug information, to help identify and troubleshoot problems, or simply ensure that the client is behaving as expected. The `EnableDebugMode` setting on `ConnectionSettings` is a convenient shorthand for enabling verbose debug information, configuring a number of settings like
11+
12+
* disabling direct streaming to capture request and response bytes
13+
* prettyfying JSON responses from Elasticsearch
14+
* collecting TCP statistics when a request is made
15+
* collecting thread pool statistics when a request is made
16+
* including the Elasticsearch stack trace in the response if there is a an error on the server side
17+
18+
```csharp
19+
IConnectionPool pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
20+
21+
var settings = new ConnectionSettings(pool)
22+
.EnableDebugMode(); <1>
23+
24+
var client = new ElasticClient(settings);
25+
26+
var response = client.Search<Project>(s => s
27+
.Query(q => q
28+
.MatchAll()
29+
)
30+
);
31+
32+
var debugInformation = response.DebugInformation; <2>
33+
```
34+
35+
1. configure debug mode
36+
2. verbose debug information
37+
38+
39+
In addition to exposing debug information on the response, debug mode will also cause the debug information to be written to the trace listeners in the `System.Diagnostics.Debug.Listeners` collection by default, when the request has completed. A delegate can be passed when enabling debug mode to perform a different action when a request has completed, using [`OnRequestCompleted`](logging-with-onrequestcompleted.md)
40+
41+
```csharp
42+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
43+
var client = new ElasticClient(new ConnectionSettings(pool)
44+
.EnableDebugMode(apiCallDetails =>
45+
{
46+
// do something with the call details e.g. send with logging framework
47+
})
48+
);
49+
```
50+
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/debugging.html
4+
---
5+
6+
# Debugging [debugging]
7+
8+
Elasticsearch.Net and NEST provide an audit trail and debug information to help you resolve issues:
9+
10+
* [](audit-trail.md)
11+
* [](debug-information.md)
12+
* [](debug-mode.md)
13+
14+

docs/reference/troubleshoot/index.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
navigation_title: Troubleshoot
3+
mapped_pages:
4+
- https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/troubleshooting.html
5+
---
6+
7+
# Troubleshoot: {{es}} .NET client [troubleshooting]
8+
9+
The client can provide rich details about what occurred in the request pipeline during the process of making a request, and can also provide the raw request and response JSON.
10+
11+
* [Logging](logging.md)
12+
* [Debugging](debugging.md)
13+
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/logging-with-fiddler.html
4+
---
5+
6+
# Logging with Fiddler [logging-with-fiddler]
7+
8+
A web debugging proxy such as [Fiddler](http://www.telerik.com/fiddler) is a useful way to capture HTTP traffic from a machine, particularly whilst developing against a local Elasticsearch cluster.
9+
10+
## Capturing traffic to a remote cluster [_capturing_traffic_to_a_remote_cluster]
11+
12+
To capture traffic against a remote cluster is as simple as launching Fiddler! You may want to also filter traffic to only show requests to the remote cluster by using the filters tab
13+
14+
:::{image} ../images/elasticsearch-client-net-api-capture-requests-remotehost.png
15+
:alt: Capturing requests to a remote host
16+
:::
17+
18+
19+
## Capturing traffic to a local cluster [_capturing_traffic_to_a_local_cluster]
20+
21+
The .NET Framework is hardcoded not to send requests for `localhost` through any proxies and as a proxy Fiddler will not receive such traffic.
22+
23+
This is easily circumvented by using `ipv4.fiddler` as the hostname instead of `localhost`
24+
25+
```csharp
26+
var isFiddlerRunning = Process.GetProcessesByName("fiddler").Any();
27+
var host = isFiddlerRunning ? "ipv4.fiddler" : "localhost";
28+
29+
var connectionSettings = new ConnectionSettings(new Uri($"http://{host}:9200"))
30+
.PrettyJson(); <1>
31+
32+
var client = new ElasticClient(connectionSettings);
33+
```
34+
35+
1. prettify json requests and responses to make them easier to read in Fiddler
36+
37+
38+
With Fiddler running, the requests and responses will now be captured and can be inspected in the Inspectors tab
39+
40+
:::{image} ../images/elasticsearch-client-net-api-inspect-requests.png
41+
:alt: Inspecting requests and responses
42+
:::
43+
44+
As before, you may also want to filter traffic to only show requests to `ipv4.fiddler` on the port on which you are running Elasticsearch.
45+
46+
:::{image} ../images/elasticsearch-client-net-api-capture-requests-localhost.png
47+
:alt: Capturing requests to localhost
48+
:::
49+
50+

0 commit comments

Comments
 (0)