Skip to content

Commit 6bb3ef1

Browse files
TamsilAmaniTamsilAmani
authored
[js] Adding logger documentation (SeleniumHQ#1321)
[deploy site]
1 parent 97c471c commit 6bb3ef1

File tree

4 files changed

+812
-256
lines changed

4 files changed

+812
-256
lines changed

‎website_and_docs/content/documentation/webdriver/troubleshooting/logging.en.md

Lines changed: 203 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -9,70 +9,209 @@ description: >
99
Each language adopts a distinctly different approach to logging information about the activity
1010
of the program.
1111

12-
## Ruby
13-
14-
Ruby uses a custom implementation of the default `Logger` class with some interesting additional features.
15-
16-
### Logger output
17-
18-
By default, logs are sent to the console in `stdout`.
19-
if you want to store the logs in a file, add this to your code:
20-
```ruby
21-
Selenium::WebDriver.logger.output = '/path/to/selenium.log'
22-
```
23-
24-
### Logger level
25-
26-
The basic levels for the Ruby logger are: `:debug`, `:info`, `:warn`, `:error`, `:fatal`
27-
28-
Selenium uses `:info` and `:debug` similar to "verbose" and "very verbose", so the default
29-
is `:warn`.
30-
31-
To change the level of the logger:
32-
```ruby
33-
Selenium::WebDriver.logger.level = :fatal
34-
```
35-
36-
**WARN**
37-
38-
Warnings include everything we want users to be aware of by default. This is mostly used
12+
### 1. Getting a logger
13+
14+
{{< tabpane langEqualsHeader=true text=true >}}
15+
{{< tab header="Java" >}}
16+
{{< alert-content >}}{{< /alert-content >}}
17+
{{< /tab >}}
18+
{{< tab header="Python" >}}
19+
{{< alert-content >}}{{< /alert-content >}}
20+
{{< /tab >}}
21+
{{< tab header="CSharp" >}}
22+
{{< alert-content >}}{{< /alert-content >}}
23+
{{< /tab >}}
24+
{{% tab header="Ruby" %}}
25+
Ruby uses a custom implementation of the default `Logger` class with some interesting additional features.
26+
27+
logger = Selenium::WebDriver.logger
28+
{{% /tab %}}
29+
{{% tab header="JavaScript" %}}
30+
const logging = require('selenium-webdriver/lib/logging')
31+
logger = logging.getLogger('webdriver')
32+
{{% /tab %}}
33+
{{< tab header="Kotlin" >}}
34+
{{< alert-content >}}{{< /alert-content >}}
35+
{{< /tab >}}
36+
{{< /tabpane >}}
37+
38+
### 2. Logger Level
39+
Logger level helps to filter out logs based on their severity.
40+
41+
{{< tabpane langEqualsHeader=true text=true >}}
42+
{{< tab header="Java" >}}
43+
{{< alert-content >}}{{< /alert-content >}}
44+
{{< /tab >}}
45+
{{< tab header="Python" >}}
46+
{{< alert-content >}}{{< /alert-content >}}
47+
{{< /tab >}}
48+
{{< tab header="CSharp" >}}
49+
{{< alert-content >}}{{< /alert-content >}}
50+
{{< /tab >}}
51+
{{% tab header="Ruby" %}}
52+
Levels are: `:debug`, `:info`, `:warn`, `:error`, `:fatal`. Default is `:warn`.
53+
To change the level of the logger:
54+
55+
Selenium::WebDriver.logger.level = :info
56+
{{% /tab %}}
57+
{{% tab header="JavaScript" %}}
58+
Levels are: `OFF`, `SEVERE`, `WARNING`, `INFO`, `DEBUG`, `FINE`, `FINER`, `FINEST`, `ALL`. Default is `OFF`.
59+
To change the level of the logger:
60+
61+
logger.setLevel(logging.Level.INFO)
62+
{{% /tab %}}
63+
{{< tab header="Kotlin" >}}
64+
{{< alert-content >}}{{< /alert-content >}}
65+
{{< /tab >}}
66+
{{< /tabpane >}}
67+
68+
**Actionable Items**
69+
70+
Things are logged as warnings if they are something the user needs to take action on. This is often used
3971
for deprecations. For various reasons, Selenium project does not follow standard Semantic Versioning practices.
4072
Our policy is to mark things as deprecated for 3 releases and then remove them.
41-
As such, Ruby logs deprecations as warnings, specifying what is changing, what needs to be
42-
used instead. It may include additional messages, and always includes an ID.
43-
44-
For example:
45-
> 2022-12-24 16:07:09 WARN Selenium [DEPRECATION] [:jwp_caps] \`Capabilities#version=\` is deprecated. Use \`Capabilities#browser_version=\` instead.
46-
47-
Because these items can get annoying, we've provided an easy way to turn them off.
48-
49-
To turn off a specific warning, set the ID to ignore:
50-
```ruby
51-
Selenium::WebDriver.logger.ignore(:jwp_caps)
52-
```
53-
It accepts an `Array` to turn off multiple IDs:
54-
```ruby
55-
Selenium::WebDriver.logger.ignore(%i[jwp_caps pause pauses])
56-
```
57-
To turn off all *deprecation* notices:
58-
```ruby
59-
Selenium::WebDriver.logger.ignore(:deprecations)
60-
```
61-
62-
**INFO**
63-
64-
This is where the most useful information gets logged. Selenium logs the endpoints and payloads
65-
sent to and received from the driver or server. This is a great way to see what Selenium is actually
66-
doing under the hood, and can be used to determine if it is Selenium code or driver code that
67-
is causing a problem. (Unfortunately, we can't blame the driver if Selenium is sending incorrect syntax).
68-
69-
**DEBUG**
70-
71-
This is less useful information where we log things about the servers and the sockets, and header information, etc.
72-
Debug mode is set if either `$DEBUG` is true or `ENV['DEBUG']` has a value.
73-
74-
-----
7573

76-
{{< alert-content >}}
77-
Descriptions of how to set and use logging in Java, Python, JavaScript, and .NET
78-
{{< /alert-content >}}
74+
{{< tabpane langEqualsHeader=true text=true >}}
75+
{{< tab header="Java" >}}
76+
{{< alert-content >}}{{< /alert-content >}}
77+
{{< /tab >}}
78+
{{< tab header="Python" >}}
79+
{{< alert-content >}}{{< /alert-content >}}
80+
{{< /tab >}}
81+
{{< tab header="CSharp" >}}
82+
{{< alert-content >}}{{< /alert-content >}}
83+
{{< /tab >}}
84+
{{% tab header="Ruby" %}}
85+
Ruby logs deprecations as warnings, specifying what is changing, what needs to be
86+
used instead. It may include additional messages, and always includes an ID.
87+
88+
For example:
89+
> 2022-12-24 16:07:09 WARN Selenium [DEPRECATION] [:jwp_caps] \`Capabilities#version=\` is deprecated. Use \`Capabilities#browser_version=\` instead.
90+
91+
Because these items can get annoying, we've provided an easy way to turn them off.
92+
93+
To turn off a specific warning, set the ID to ignore:
94+
95+
Selenium::WebDriver.logger.ignore(:jwp_caps)
96+
97+
It accepts an `Array` to turn off multiple IDs:
98+
99+
Selenium::WebDriver.logger.ignore(%i[jwp_caps pause pauses])
100+
101+
To turn off all *deprecation* notices:
102+
103+
Selenium::WebDriver.logger.ignore(:deprecations)
104+
{{% /tab %}}
105+
{{< tab header="JavaScript" >}}
106+
{{< alert-content />}}
107+
{{< /tab >}}
108+
{{< tab header="Kotlin" >}}
109+
{{< alert-content >}}{{< /alert-content >}}
110+
{{< /tab >}}
111+
{{< /tabpane >}}
112+
113+
**Useful Information**
114+
115+
This is the default level where Selenium logs things that users should be aware of but do not need to take actions on.
116+
It presents information such as requests and responses between driver and server, payload, etc.
117+
118+
Different languages have different level to log information.
119+
120+
{{< tabpane langEqualsHeader=true text=true >}}
121+
{{< tab header="Java" >}}
122+
{{< alert-content >}}{{< /alert-content >}}
123+
{{< /tab >}}
124+
{{< tab header="Python" >}}
125+
{{< alert-content >}}{{< /alert-content >}}
126+
{{< /tab >}}
127+
{{< tab header="CSharp" >}}
128+
{{< alert-content >}}{{< /alert-content >}}
129+
{{< /tab >}}
130+
{{% tab header="Ruby" %}}
131+
Because the Ruby `Logger` class only has one "debug" level, Selenium is currently using the `:info` level as a general debug mode, and `:debug` as a lower level debug mode.
132+
To bring things in line with other languages, we are considering <a href="https://github.com/SeleniumHQ/selenium/issues/11797">changing this behavior</a>.
133+
For now, both info and warnings are handled at the default `:warn` level.
134+
{{% /tab %}}
135+
{{% tab header="JavaScript" %}}
136+
Logs useful information at level: `INFO`
137+
{{% /tab %}}
138+
{{< tab header="Kotlin" >}}
139+
{{< alert-content >}}{{< /alert-content >}}
140+
{{< /tab >}}
141+
{{< /tabpane >}}
142+
143+
**Debugging Details**
144+
145+
The debug log level is used for information that may be needed for diagnosing issues and troubleshooting problems.
146+
147+
{{< tabpane langEqualsHeader=true text=true >}}
148+
{{< tab header="Java" >}}
149+
{{< alert-content >}}{{< /alert-content >}}
150+
{{< /tab >}}
151+
{{< tab header="Python" >}}
152+
{{< alert-content >}}{{< /alert-content >}}
153+
{{< /tab >}}
154+
{{< tab header="CSharp" >}}
155+
{{< alert-content >}}{{< /alert-content >}}
156+
{{< /tab >}}
157+
{{% tab header="Ruby" %}}
158+
Logs debugging details at level: `:info` and `:debug`
159+
{{% /tab %}}
160+
{{% tab header="JavaScript" %}}
161+
Logs debugging details at level: `FINER` and `FINEST`
162+
{{% /tab %}}
163+
{{< tab header="Kotlin" >}}
164+
{{< alert-content >}}{{< /alert-content >}}
165+
{{< /tab >}}
166+
{{< /tabpane >}}
167+
168+
### 3. Log Output:
169+
Logs can be displayed on `stdout` or stored in a file.
170+
171+
{{< tabpane langEqualsHeader=true text=true >}}
172+
{{< tab header="Java" >}}
173+
{{< alert-content >}}{{< /alert-content >}}
174+
{{< /tab >}}
175+
{{< tab header="Python" >}}
176+
{{< alert-content >}}{{< /alert-content >}}
177+
{{< /tab >}}
178+
{{< tab header="CSharp" >}}
179+
{{< alert-content >}}{{< /alert-content >}}
180+
{{< /tab >}}
181+
{{% tab header="Ruby" %}}
182+
By default, logs are sent to the console in `stdout`.
183+
To store the logs in a file:
184+
185+
Selenium::WebDriver.logger.output = '/path/to/selenium.log'
186+
187+
Sample Output:
188+
189+
2023-02-08 12:31:23 INFO Selenium -> POST session/8b83ff54712d0a247937d045f8c8e171/url
190+
2023-02-08 12:31:23 INFO Selenium >>> http://127.0.0.1:9515/session/8b83ff54712d0a247937d045f8c8e171/url | {"url":"https://www.selenium.dev/selenium/web/web-form.html"}
191+
2023-02-08 12:31:23 INFO Selenium <- {"value":null}
192+
{{% /tab %}}
193+
{{% tab header="JavaScript" %}}
194+
Send logs to console output:
195+
196+
logging.installConsoleHandler()
197+
198+
Sample Output:
199+
200+
[2023-03-21T22:28:20Z] [FINER] [webdriver.http.Executor] >>> POST /session/0208994573cca3250a1066424c1b915c/url
201+
[2023-03-21T22:28:22Z] [FINER] [webdriver.http.Executor] >>>
202+
POST /session/0208994573cca3250a1066424c1b915c/url HTTP/1.1
203+
accept: application/json; charset=utf-8
204+
205+
{"url":"https://www.selenium.dev/selenium/web/web-form.html"}
206+
<<<
207+
HTTP/1.1 200
208+
content-length: 14
209+
content-type: application/json; charset=utf-8
210+
cache-control: no-cache
211+
212+
{"value":null}
213+
{{% /tab %}}
214+
{{< tab header="Kotlin" >}}
215+
{{< alert-content >}}{{< /alert-content >}}
216+
{{< /tab >}}
217+
{{< /tabpane >}}

0 commit comments

Comments
 (0)