docs: update "recording a trace" section (#8368)

docs/src/api/class-timeouterror.md

@@ -23,19 +23,6 @@ const playwright = require('playwright');
 })();
 ```
 
-```python sync
-from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeoutError
-
-with sync_playwright() as p:
-    browser = p.chromium.launch()
-    page = browser.new_page()
-    try:
-      page.click("text=Example", timeout=100)
-    except PlaywrightTimeoutError:
-      print("Timeout!")
-    browser.close()
-```
-
 ```python async
 import asyncio
 from playwright.async_api import async_playwright, TimeoutError as PlaywrightTimeoutError
@@ -56,6 +43,19 @@ async def main():
 asyncio.run(main())
 ```
 
+```python sync
+from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeoutError
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page()
+    try:
+      page.click("text=Example", timeout=100)
+    except PlaywrightTimeoutError:
+      print("Timeout!")
+    browser.close()
+```
+
 ```java
 package org.example;
 

docs/src/trace-viewer.md

@@ -10,10 +10,36 @@ Playwright Trace Viewer is a GUI tool that helps exploring recorded Playwright t
 <!-- TOC -->
 
 ## Recording a trace
+* langs: js
 
-Traces can be recorded using the [`property: BrowserContext.tracing`] API as follows:
+Set the `trace: 'on-first-retry'` option in the test configuration file. This will produce `trace.zip` file for each test that was retried.
 
-```js
+```js js-flavor=js
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
+  retries: 1,
+  use: {
+    trace: 'on-first-retry',
+  },
+};
+
+module.exports = config;
+```
+
+```js js-flavor=ts
+import { PlaywrightTestConfig } from '@playwright/test';
+const config: PlaywrightTestConfig = {
+  retries: 1,
+  use: {
+    trace: 'on-first-retry',
+  },
+};
+export default config;
+```
+
+```js js-flavor=library
 const browser = await chromium.launch();
 const context = await browser.newContext();
 
@@ -27,6 +53,21 @@ await page.goto('https://playwright.dev');
 await context.tracing.stop({ path: 'trace.zip' });
 ```
 
+You can also use `trace: 'retain-on-failure'` if you do not enable retries but still want traces for failed tests.
+
+Available options to record a trace:
+- `'off'` - Do not record a trace.
+- `'on'` - Record a trace for each test.
+- `'retain-on-failure'` - Record a trace for each test, but remove it from successful test runs.
+- `'on-first-retry'` - Record a trace only when retrying a test for the first time.
+
+If you are not using Playwright Test, use the [`property: BrowserContext.tracing`] API instead.
+
+## Recording a trace
+* langs: java, csharp, python
+
+Traces can be recorded using the [`property: BrowserContext.tracing`] API as follows:
+
 ```java
 Browser browser = browserType.launch();
 BrowserContext context = browser.newContext();