docs: create how-to-guides section (#708)

Kludex · web-flow · commit 9d1491cb28d2 · 2024-12-20T10:45:44.000Z
diff --git a/docs/guides/onboarding-checklist/add-auto-tracing.md b/docs/guides/onboarding-checklist/add-auto-tracing.md
@@ -22,7 +22,7 @@ main()
 ```
 
 !!! note
-    Generator functions will not be traced for reasons explained [here](../advanced/generators.md).
+    Generator functions will not be traced for reasons explained [here](../../reference/advanced/generators.md).
 
 ## Only tracing functions above a minimum duration
 
diff --git a/docs/guides/web-ui/live.md b/docs/guides/web-ui/live.md
@@ -12,10 +12,14 @@ To search the live view, click `Search your spans` (keyboard shortcut `/`), this
 
 ### SQL Search
 
-For confident SQL users, write your queries directly here. For devs who want a bit of help, try the new [PydanticAI](https://ai.pydantic.dev/) feature which generates a SQL query based on your prompt. You can also review the fields available and populate your SQL automatically using the `Reference` list, see more on this below.
+For confident SQL users, write your queries directly here. For devs who want a bit of help,
+try the new [PydanticAI](https://ai.pydantic.dev/) feature which generates a SQL query based on your prompt.
+You can also review the fields available and populate your SQL automatically using the `Reference` list, see more on this below.
 
-**WHERE clause**  
-As the greyed out `SELECT * FROM RECORDS WHERE` implies, you're searching inside the `WHERE` clause of a SQL query. It has auto-complete & schema hints, so try typing something to get a reminder. To run your query click `Run` or keyboard shortcut `cmd+enter` (or `ctrl+enter` on windows/linux).
+**WHERE clause**
+As the greyed out `SELECT * FROM RECORDS WHERE` implies, you're searching inside the `WHERE` clause of a SQL query.
+It has auto-complete & schema hints, so try typing something to get a reminder. To run your query click `Run` or
+keyboard shortcut `cmd+enter` (or `ctrl+enter` on Windows/Linux).
 
 Note: you can run more complex queries on the [explore screen](explore.md)
 
@@ -62,7 +66,7 @@ If you're not sure where to start, scroll down to the `Start here` for beginner-
 
 ### Ask in Language -> Get SQL
 
-Write your question in your native language, and the model will convert that question to a SQL query. 
+Write your question in your native language, and the model will convert that question to a SQL query.
 
 ![Search box natural language](../../images/guide/live-view-natural-language.png)
 
@@ -74,18 +78,23 @@ Under the hood this feature uses an LLM running with [PydanticAI](https://github
 
 Reference: A list of pre-populated query clauses. Clicking any of the clauses will populate the SQL editor, and (where applicable) you can choose a value from the autopopulated dropdown.
 
-This list gives you a powerful way to rapidly generate the query you need, while simultaneously learning more about all the ways you can search your data. Clicking multiple clauses will add them to your query with a SQL `AND` statement. If you'd like something other than an `AND` statement, you can replace this with alternative SQL operators like `OR`, or `NOT`.  
-
+This list gives you a powerful way to rapidly generate the query you need, while simultaneously
+learning more about all the ways you can search your data. Clicking multiple clauses will add them
+to your query with a SQL `AND` statement. If you'd like something other than an `AND` statement, you
+can replace this with alternative SQL operators like `OR`, or `NOT`.
 
 ## Details panel closed
 
 ![Logfire live view collapsed](../../images/guide/live-view-collapsed-annotated.png)
 
 This is what you'll see when you come to the live view of a project with some data.
 
-1. **Organization and project labels:** In this example, the organization is `christophergs`, and the project is `docs-app`. You can click the organization name to go to the organization overview page; the project name is a link to this page.
+1. **Organization and project labels:** In this example, the organization is `christophergs`, and
+   the project is `docs-app`. You can click the organization name to go to the organization overview page;
+   the project name is a link to this page.
 
-2. **Environment:** In the above screenshot, this is set to `all envs`. See the [environments docs](../advanced/environments.md) for details.
+2. **Environment:** In the above screenshot, this is set to `all envs`.
+    See the [environments docs](../../how-to-guides/environments.md) for details.
 
 3. **Timeline:** This shows a histogram of the counts of spans matching your query over time. The blue-highlighted section corresponds to the time range currently visible in the scrollable list of traces below. You can click at points on this line to move to viewing logs from that point in time.
 
diff --git a/docs/how-to-guides/alternative-backends.md b/docs/how-to-guides/alternative-backends.md
diff --git a/docs/how-to-guides/alternative-clients.md b/docs/how-to-guides/alternative-clients.md
@@ -7,7 +7,7 @@ these [environment variables](https://opentelemetry.io/docs/languages/sdk-config
 - `OTEL_EXPORTER_OTLP_ENDPOINT=https://logfire-api.pydantic.dev` for both traces and metrics, or:
     - `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces` for just traces
     - `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://logfire-api.pydantic.dev/v1/metrics` for just metrics
-- `OTEL_EXPORTER_OTLP_HEADERS='Authorization=your-write-token'` - see [Creating Write Tokens](./creating-write-tokens.md)
+- `OTEL_EXPORTER_OTLP_HEADERS='Authorization=your-write-token'` - see [Create Write Tokens](./create-write-tokens.md)
   to obtain a write token and replace `your-write-token` with it.
 - `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` to export in Protobuf format over HTTP (not gRPC).
   The **Logfire** backend supports both Protobuf and JSON, but only over HTTP for now. Some SDKs (such as Python) already use this value as the default so setting this isn't required, but other SDKs use `grpc` as the default.
diff --git a/docs/how-to-guides/create-write-tokens.md b/docs/how-to-guides/create-write-tokens.md
@@ -1,6 +1,6 @@
 To send data to **Logfire**, you need to create a write token.
 A write token is a unique identifier that allows you to send data to a specific **Logfire** project.
-If you set up Logfire according to the [getting started guide](../../index.md), you already have a write token locally tied to the project you created.
+If you set up Logfire according to the [getting started guide](../index.md), you already have a write token locally tied to the project you created.
 But if you want to configure other computers to write to that project, for example in a deployed application, you need to create a new write token.
 
 You can create a write token by following these steps:
diff --git a/docs/how-to-guides/environments.md b/docs/how-to-guides/environments.md
@@ -23,9 +23,10 @@ If you are using languages other than Python, you can set the environment like t
 ---
 
 Once set, you will see your environment in the Logfire UI `all envs` dropdown,
-which is present on the [Live View](../web-ui/live.md), [Dashboards](../web-ui/dashboards.md) and [Explore](../web-ui/explore.md) pages:
+which is present on the [Live View](../guides/web-ui/live.md), [Dashboards](../guides/web-ui/dashboards.md)
+and [Explore](../guides/web-ui/explore.md) pages:
 
-![Environments](../../images/guide/environments.png)
+![Environments](../images/guide/environments.png)
 
 !!! info
     When using an environment for the first time, it may take a **few minutes** for the environment to appear in the UI.
@@ -55,5 +56,5 @@ environment name.
 ## Should I use environments or projects?
 
 Environments are more lightweight than projects. Projects give you the ability to assign specific
-user groups and permissions levels (see this [organization structure diagram](../../reference/organization-structure.md)
+user groups and permissions levels (see this [organization structure diagram](../reference/organization-structure.md)
 for details). So if you need to allow different team members to view dev vs. prod traces, then projects would be a better fit.
diff --git a/docs/how-to-guides/link-to-code-source.md b/docs/how-to-guides/link-to-code-source.md
@@ -5,7 +5,7 @@
 
 We support linking to the source code on GitHub, GitLab, and any other VCS provider that uses the same URL format.
 
-![Link to GitHub](../../images/guide/link-to-github.gif)
+![Link to GitHub](../images/guide/link-to-github.gif)
 
 ## Usage
 
@@ -40,5 +40,5 @@ OTEL_RESOURCE_ATTRIBUTES=${OTEL_RESOURCE_ATTRIBUTES},vcs.repository.ref.revision
 OTEL_RESOURCE_ATTRIBUTES=${OTEL_RESOURCE_ATTRIBUTES},vcs.root.path=.
 ```
 
-[help]: ../../help.md
+[help]: ../help.md
 [otel-resource-attributes]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration
diff --git a/docs/how-to-guides/query-api.md b/docs/how-to-guides/query-api.md
@@ -10,7 +10,7 @@ See [here](#additional-configuration) for more details about the available respo
 
 ## How to Create a Read Token
 
-If you've set up Logfire following the [getting started guide](../../index.md), you can generate read tokens from
+If you've set up Logfire following the [getting started guide](../index.md), you can generate read tokens from
 the Logfire web interface, for use accessing the Logfire Query API.
 
 To create a read token:
diff --git a/docs/how-to-guides/sampling.md b/docs/how-to-guides/sampling.md
diff --git a/docs/how-to-guides/scrubbing.md b/docs/how-to-guides/scrubbing.md
@@ -85,9 +85,9 @@ User details: User(id=123, password='secret')
 This is necessary so that safe messages such as 'Password is correct' are not redacted completely.
 
 Using f-strings (e.g. `logfire.info(f'User details: {user}')`) *is* safe if `inspect_arguments` is enabled (the default in Python 3.11+) and working correctly.
-[See here](../onboarding-checklist/add-manual-tracing.md#f-strings) for more information.
+[See here](../guides/onboarding-checklist/add-manual-tracing.md#f-strings) for more information.
 
-In short, don't format the message yourself. This is also a good practice in general for [other reasons](../onboarding-checklist/add-manual-tracing.md#messages-and-span-names).
+In short, don't format the message yourself. This is also a good practice in general for [other reasons](../guides/onboarding-checklist/add-manual-tracing.md#messages-and-span-names).
 
 ### Keep sensitive data out of URLs
 
diff --git a/docs/index.md b/docs/index.md
@@ -52,7 +52,8 @@ logfire auth
 ## Instrument your project {#instrument}
 === ":material-cog-outline: Development"
     !!! tip "Development setup"
-        During development, we recommend using the CLI to configure Logfire. You can also use a [write token](guides/advanced/creating-write-tokens.md).
+        During development, we recommend using the CLI to configure Logfire.
+        You can also use a [write token](how-to-guides/create-write-tokens.md).
 
     1. Set your project
 
@@ -72,8 +73,8 @@ logfire auth
     logfire.info('Hello, {name}!', name='world')  # (2)!
     ```
 
-    1. The `configure()` method should be called once before logging to initialize **Logfire**.
-    2. This will log `Hello world!` with `info` level.
+    3. The `configure()` method should be called once before logging to initialize **Logfire**.
+    4. This will log `Hello world!` with `info` level.
 
     !!! info ""
         Other [log levels][logfire.Logfire] are also available to use, including `trace`, `debug`, `notice`, `warn`,
diff --git a/docs/integrations/event-streams/airflow.md b/docs/integrations/event-streams/airflow.md
@@ -162,4 +162,4 @@ otel_task_log_event = True
 [OpenTelemetry Collector]: https://opentelemetry.io/docs/collector/
 [OpenTelemetry Collector installation]: https://opentelemetry.io/docs/collector/installation/
 [OpenTelemetry Collector Receiver]: https://opentelemetry.io/docs/collector/configuration/#receivers
-[write-token]: ../../guides/advanced/creating-write-tokens.md
+[write-token]: ../../how-to-guides/create-write-tokens.md
diff --git a/docs/integrations/web-frameworks/index.md b/docs/integrations/web-frameworks/index.md
@@ -47,7 +47,7 @@ To replace the `Authorization` header value with `[REDACTED]` to avoid leaking u
 OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS="Authorization"
 ```
 
-(although usually it's better to rely on **Logfire**'s [scrubbing](../../guides/advanced/scrubbing.md) feature)
+(although usually it's better to rely on **Logfire**'s [scrubbing](../../how-to-guides/scrubbing.md) feature)
 
 ## Query HTTP requests duration per percentile
 
diff --git a/docs/reference/advanced/backfill.md b/docs/reference/advanced/backfill.md
diff --git a/docs/reference/advanced/generators.md b/docs/reference/advanced/generators.md
diff --git a/docs/reference/advanced/testing.md b/docs/reference/advanced/testing.md
diff --git a/docs/reference/examples.md b/docs/reference/examples.md
@@ -18,7 +18,7 @@ This example is a simple Python financial calculator app using Flask and SQLAlch
 
 ## JavaScript
 
-Currently we only have a Python SDK, but the Logfire backend and UI support data sent by any OpenTelemetry client. See the [alternative clients guide](../guides/advanced/alternative-clients.md) for details on setting up OpenTelemetry in any language. We're working on a JavaScript SDK, but in the meantime here are some examples of using plain OpenTelemetry in JavaScript:
+Currently we only have a Python SDK, but the Logfire backend and UI support data sent by any OpenTelemetry client. See the [alternative clients guide](../how-to-guides/alternative-clients.md) for details on setting up OpenTelemetry in any language. We're working on a JavaScript SDK, but in the meantime here are some examples of using plain OpenTelemetry in JavaScript:
 
 ### Cloudflare worker example
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -65,7 +65,7 @@ Logfire is built on top of OpenTelemetry, which means that it supports all the l
 Still, we are planning to create custom SDKs for JavaScript, TypeScript, and Rust, and make sure that the
 attributes are displayed in a nice way in the Logfire UI — as they are for Python.
 
-For now, you can check our [Alternative Clients](guides/advanced/alternative-clients.md) section to see how
+For now, you can check our [Alternative Clients](how-to-guides/alternative-clients.md) section to see how
 you can send data to Logfire from other languages.
 
 See [this GitHub issue][language-support-gh-issue] for more information.
diff --git a/docs/why.md b/docs/why.md
@@ -12,15 +12,15 @@ From the team behind Pydantic, **Logfire** is an observability platform built on
 
     Logfire's dashboard is simple relative to the power it provides, ensuring your entire engineering team will actually use it. Time-to-first-log should be less than 5 minutes.
 
-    [:octicons-arrow-right-24: Read more](#simplicity-and-power-)
+    [:octicons-arrow-right-24: Read more](#simplicity-and-power)
 
 -   :snake:{ .lg .middle } __Python-centric Insights__
 
     ---
 
     From rich display of **Python objects**, to **event-loop telemetry**, to **profiling Python code &amp; database queries**, Logfire gives you unparalleled visibility into your Python application's behavior.
 
-    [:octicons-arrow-right-24: Read more](#python-centric-insights-material-snake)
+    [:octicons-arrow-right-24: Read more](#python-centric-insights)
 
 -   :simple-pydantic:{ .lg .middle } __Pydantic Integration__
 
@@ -38,23 +38,23 @@ From the team behind Pydantic, **Logfire** is an observability platform built on
 
     Logfire is an opinionated wrapper around OpenTelemetry, allowing you to leverage existing tooling, infrastructure, and instrumentation for many common Python packages, and enabling support for virtually any language.
 
-    [:octicons-arrow-right-24: Read more](#opentelemetry-under-the-hood-)
+    [:octicons-arrow-right-24: Read more](#opentelemetry-under-the-hood)
 
 -   :simple-instructure:{ .lg .middle } __Structured Data__
 
     ---
 
     Include your Python objects in Logfire calls (lists, dict, dataclasses, Pydantic models, DataFrames, and more), and it'll end up as structured data in our platform ready to be queried.
 
-    [:octicons-arrow-right-24: Read more](#structured-data-and-sql--sql)
+    [:octicons-arrow-right-24: Read more](#sql)
 
 -   :abacus:{ .lg .middle } __SQL__
 
     ---
 
     Query your data using standard SQL — all the control and (for many) nothing new to learn. Using SQL also means you can query your data with existing BI tools and database querying libraries.
 
-    [:octicons-arrow-right-24: Read more](#structured-data-and-sql--sql)
+    [:octicons-arrow-right-24: Read more](#sql)
 
 </div>
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -79,18 +79,15 @@ nav:
           - Dashboards: guides/web-ui/dashboards.md
           - Alerts (Beta): guides/web-ui/alerts.md
           - SQL Explorer: guides/web-ui/explore.md
-      - Advanced User Guide:
-          - Environments: guides/advanced/environments.md
-          - Alternative Clients: guides/advanced/alternative-clients.md
-          - Alternative Backends: guides/advanced/alternative-backends.md
-          - Sampling: guides/advanced/sampling.md
-          - Scrubbing: guides/advanced/scrubbing.md
-          - Generators: guides/advanced/generators.md
-          - Creating Write Tokens: guides/advanced/creating-write-tokens.md
-          - Query API: guides/advanced/query-api.md
-          - Link to Code Source: guides/advanced/link-to-code-source.md
-          - Testing: guides/advanced/testing.md
-          - Backfill: guides/advanced/backfill.md
+  - How To - Guides:
+      - Create Write Tokens: how-to-guides/create-write-tokens.md
+      - Use different environments: how-to-guides/environments.md
+      - Link to Code Source: how-to-guides/link-to-code-source.md
+      - Use Alternative Clients: how-to-guides/alternative-clients.md
+      - Use Alternative Backends: how-to-guides/alternative-backends.md
+      - Implement Sampling Strategies: how-to-guides/sampling.md
+      - Export your Logfire Data: how-to-guides/query-api.md
+      - Scrub Sensitive Data: how-to-guides/scrubbing.md
   - Integrations:
       - Integrations: integrations/index.md
       - LLMs:
@@ -133,6 +130,10 @@ nav:
       - Stripe: integrations/stripe.md
       - AWS Lambda: integrations/aws-lambda.md
   - Reference:
+      - Advanced:
+          - Generators: reference/advanced/generators.md
+          - Testing: reference/advanced/testing.md
+          - Backfill: reference/advanced/backfill.md
       - Examples: reference/examples.md
       - Configuration: reference/configuration.md
       - Organization Structure: reference/organization-structure.md
@@ -225,9 +226,21 @@ plugins:
         "guides/web_ui/dashboards.md": "guides/web-ui/dashboards.md"
         "guides/web_ui/alerts.md": "guides/web-ui/alerts.md"
         "guides/web_ui/explore.md": "guides/web-ui/explore.md"
-        "guides/advanced/alternative_backends.md": "guides/advanced/alternative-backends.md"
-        "guides/advanced/creating_write_tokens.md": "guides/advanced/creating-write-tokens.md"
-        "guides/advanced/index.md": "guides/advanced/environments.md"
+        "guides/advanced/generators.md": "reference/advanced/generators.md"
+        "guides/advanced/testing.md": "reference/advanced/testing.md"
+        "guides/advanced/backfill.md": "reference/advanced/backfill.md"
+        "guides/advanced/query_api.md": "how-to-guides/query-api.md"
+        "guides/advanced/query-api.md": "how-to-guides/query-api.md"
+        "guides/advanced/scrubbing.md": "how-to-guides/scrubbing.md"
+        "guides/advanced/sampling.md": "how-to-guides/sampling.md"
+        "guides/advanced/alternative-clients.md": "how-to-guides/alternative-clients.md"
+        "guides/advanced/link-to-code-source.md": "how-to-guides/link-to-code-source.md"
+        "guides/advanced/alternative_backends.md": "how-to-guides/alternative-backends.md"
+        "guides/advanced/alternative-backends.md": "how-to-guides/alternative-backends.md"
+        "guides/advanced/creating_write_tokens.md": "how-to-guides/create-write-tokens.md"
+        "guides/advanced/creating-write-tokens.md": "how-to-guides/create-write-tokens.md"
+        "guides/advanced/index.md": "how-to-guides/environments.md"
+        "guides/advanced/environments.md": "how-to-guides/environments.md"
         "integrations/system_metrics.md": "integrations/system-metrics.md"
         "integrations/third_party/index.md": "integrations/index.md"
         "integrations/third-party/index.md": "integrations/index.md"
@@ -281,7 +294,6 @@ plugins:
         "api/integrations/pydantic.md": "reference/api/pydantic.md"
         "api/integrations/logging.md": "reference/api/logfire.md#logfire.LogfireLoggingHandler"
         "guides/onboarding_checklist/add_metrics.md": "guides/onboarding-checklist/add-metrics.md"
-        "guides/advanced/query_api.md": "guides/advanced/query-api.md"
         "guides/index.md": "index.md"
         "why-logfire/index.md": "why.md"
         "why-logfire/pydantic.md": "why.md"
