Merge pull request #2076 from shykes/docs

Docs: various improvements

docs/core-concepts/1218-cli-telemetry.md

@@ -1,20 +0,0 @@
----
-slug: /1218/cli-telemetry
-displayed_sidebar: europa
----
-
-# CLI Telemetry
-
-The dagger CLI implements telemetry that provides information about the usage from the Dagger Community. Although optional, this helps us to improve dagger by measuring the usage of the main features.
-
-## What is tracked?
-
-Command names are tracked along with the version of dagger and the platform it's running on. CLI telemetry events are anonymized for privacy purposes, they are not linked to a specific identity.
-
-If you want to know more, you can check the telemetry implementation in dagger's source code.
-
-## Can I disable the telemetry?
-
-Dagger implements [the DNT (Console Do Not Track) standard](https://consoledonottrack.com/).
-
-As a result, you can disable the telemetry by setting the environment variable `DO_NOT_TRACK=1` before running dagger.

docs/core-concepts/1221-action.md

@@ -34,7 +34,7 @@ A composite action's lifecycle has 4 stages:
 3. Discovery
 4. Execution
 
-## Definition
+### Definition
 
 A new action is *defined* in a declarative template called a [CUE definition](https://cuetorials.com/overview/foundations/#definitions). This definition describes the action's inputs, outputs, sub-actions, and the wiring between them.
 
@@ -76,7 +76,7 @@ Also note the free-form structure: an action definition is not structured by a r
 
 There are no constraints to an action's field names or types.
 
-## Integration
+### Integration
 
 Action definitions cannot be executed directly: they must be integrated into a plan.
 
@@ -113,7 +113,7 @@ Note that `#AddHello` was integrated *directly* into the plan, whereas `core.#Wr
 
 To learn more about the structure of a plan, see [it all begins with a plan](./1202-plan).
 
-## Discovery
+### Discovery
 
 Once integrated into a plan, actions can be discovered by end users, by using the familiar convention of usage messages:
 
@@ -131,7 +131,7 @@ Flags:
   [...]
 ```
 
-## Execution
+### Execution
 
 Once the end user has discovered the action that they need, they can execute it with `dagger do`. For example:
 

docs/guides/1216-docker-cli-load.md

@@ -11,10 +11,10 @@ It can be useful to debug or test a build locally before pushing.
 
 ## Local daemon
 
-```cue file=./plans/docker-cli-load/local.cue
+```cue file=../plans/docker-cli-load/local.cue
 ```
 
 ## Remote daemon, via SSH
 
-```cue file=./plans/docker-cli-load/ssh.cue
+```cue file=../plans/docker-cli-load/ssh.cue
 ```

docs/guides/1217-docker-cli-run.md

@@ -9,15 +9,15 @@ There's a `universe.dagger.io/docker/cli` package that allows you to run docker
 
 ## Local daemon
 
-```cue file=./plans/docker-cli-run/local.cue
+```cue file=../plans/docker-cli-run/local.cue
 ```
 
 ## Remote daemon, via SSH
 
-```cue file=./plans/docker-cli-run/ssh.cue
+```cue file=../plans/docker-cli-run/ssh.cue
 ```
 
 ## Remote daemon, via HTTPS
 
-```cue file=./plans/docker-cli-run/tcp.cue
+```cue file=../plans/docker-cli-run/tcp.cue
 ```

docs/guides/1218-cli-telemetry.md

@@ -0,0 +1,31 @@
+---
+slug: /1218/cli-telemetry
+displayed_sidebar: europa
+---
+
+# Understanding CLI Telemetry
+
+## Overview
+
+By default, the dagger CLI sends anonymized telemetry to dagger.io. This allows us to improve Dagger by understanding how it is used.
+Telemetry is optional and can be disabled at any time. If you are willing and able to leave telemetry enabled: thank you! This will help
+us better understand how Dagger is used, and will allow us to improve your experience.
+
+## What is tracked?
+
+The following information is included in telemetry:
+
+* Dagger version
+* Platform information
+* Command run
+* Anonymous device ID
+
+We use telemetry for aggregate analysis, and do not tie telemetry events to a specific identity.
+
+Our telemetry implementation is open-source and can be reviewed [here](https://github.com/dagger/dagger/blob/main/telemetry/telemetry.go).
+
+## Disabling telemetry
+
+Dagger implements the [(Console Do Not Track) standard](https://consoledonottrack.com/).
+
+As a result, you can disable the telemetry by setting the environment variable `DO_NOT_TRACK=1` before running dagger.

docs/guides/1223-custom-buildkit.md

@@ -0,0 +1,38 @@
+---
+slug: /1223/custom-buildkit/
+---
+
+# Customizing your Buildkit installation
+
+## Using a custom buildkit daemon
+
+Dagger can be configured to use an existing buildkit daemon, running either locally or remotely. This can be done using the environment variable `BUILDKIT_HOST`.
+
+To use a buildkit daemon listening on TCP port `1234` on localhost:
+
+```shell
+export BUILDKIT_HOST=tcp://localhost:1234
+```
+
+To use a buildkit daemon running in a container named "super-buildkit" on the local docker host:
+
+```shell
+export BUILDKIT_HOST=docker-container://super-buildkit
+```
+
+## OpenTracing Support
+
+Both Dagger and buildkit support opentracing. To capture traces to
+[Jaeger](https://github.com/jaegertracing/jaeger), set the `JAEGER_TRACE` environment variable to the collection address.
+
+A `docker-compose` file is available to help bootstrap the tracing environment:
+
+```shell
+docker-compose -f ./dagger-main/tracing.compose.yaml up -d
+export JAEGER_TRACE=localhost:6831
+export BUILDKIT_HOST=docker-container://dagger-buildkitd-jaeger
+
+dagger up
+```
+
+You can then go to [http://localhost:16686/](http://localhost:16686/) in your browser to see the traces.

website/sidebars.js

@@ -100,7 +100,6 @@ module.exports = {
         "core-concepts/client",
         "core-concepts/secrets",
         "core-concepts/what-is-cue",
-        "core-concepts/cli-telemetry",
       ],
     },
     {
@@ -108,7 +107,7 @@ module.exports = {
       label: "Guides",
       collapsible: false,
       collapsed: false,
-      items: ["guides/container-images"],
+      items: ["guides/container-images", "guides/cli-telemetry", "guides/docker-cli-load", "guides/docker-cli-run"],
     },
     {
       type: "category",