From 137cb7f619ed042922994a86b8e5d05aba200445 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc Date: Tue, 17 Dec 2024 17:58:40 -0700 Subject: [PATCH 1/4] Fixing broken links --- docs/admin/observability/tracing.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin/observability/tracing.mdx b/docs/admin/observability/tracing.mdx index 9973b76ce..138db89d1 100644 --- a/docs/admin/observability/tracing.mdx +++ b/docs/admin/observability/tracing.mdx @@ -16,9 +16,9 @@ The quickest way to get started with HTTP tracing is to deploy our bundled Jaege To deploy our bundled Jaeger backend, follow the instructions for your deployment type: -- [Kubernetes with Helm](/admin/deploy/kubernetes/helm#enable-the-bundled-jaeger-deployment) -- [Kubernetes with Kustomize](/admin/deploy/kubernetes/configure#deploy-opentelemetry-collector-with-jaeger-as-tracing-backend) -- [Docker Compose](/admin/deploy/docker-compose/configuration#enable-http-tracing) +- [Kubernetes with Helm](/admin/deploy/kubernetes#enable-the-bundled-jaeger-deployment) +- [Kubernetes with Kustomize](/admin/deploy/kubernetes/configure#deploy-the-bundled-opentelemetry-collector-and-jaeger) +- [Docker Compose](/admin/deploy/docker-compose/configuration#deploy-the-bundled-jaeger) Then configure your Site Configuration: From a0e191284abf02b727b6cee34716d2fdf56aa91b Mon Sep 17 00:00:00 2001 From: Marc LeBlanc Date: Tue, 17 Dec 2024 18:50:48 -0700 Subject: [PATCH 2/4] Fixing broken links --- docs/admin/observability/opentelemetry.mdx | 33 +++++++++++----------- docs/admin/observability/tracing.mdx | 22 +++++++++------ 2 files changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/admin/observability/opentelemetry.mdx b/docs/admin/observability/opentelemetry.mdx index ca4db075b..b7fe8c7fe 100644 --- a/docs/admin/observability/opentelemetry.mdx +++ b/docs/admin/observability/opentelemetry.mdx @@ -16,9 +16,9 @@ Sourcegraph's bundled otel-collector is deployed via Docker image, and is config For details on how to deploy the otel-collector, and where to find its configuration file, refer to the docs page specific to your deployment type: -- [Kubernetes via Helm](/admin/deploy/kubernetes#opentelemetry-collector) -- [Kubernetes via Kustomize](/admin/deploy/kubernetes/configure#tracing) -- [Docker Compose](/admin/deploy/docker-compose/operations#opentelemetry-collector) +- [Kubernetes with Helm](/admin/deploy/kubernetes#configure-opentelemetry-collector-to-use-an-external-tracing-backend) +- [Kubernetes with Kustomize](/admin/deploy/kubernetes/configure#deploy-opentelemetry-collector-to-use-an-external-tracing-backend) +- [Docker Compose](/admin/deploy/docker-compose/configuration#configure-an-external-tracing-backend) ## HTTP Tracing Backends @@ -61,7 +61,7 @@ service: ## Sampling traces -To reduce the volume of traces exported, the collector can be configured to apply sampling. Sourcegraph includes the [probabilistic](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/probabilisticsamplerprocessor) and [tail](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/tailsamplingprocessor/README) samplers in the bundled collector. +To reduce the volume of traces exported, the collector can be configured to apply sampling. Sourcegraph includes the [probabilistic](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/probabilisticsamplerprocessor) and [tail](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/tailsamplingprocessor/README.md) samplers in the bundled collector. > NOTE: If sampling is enabled, the sampling mechanism will be applied to all traces, regardless if a request was explicitly requested to be traced. @@ -90,7 +90,7 @@ service: ### Tail sampling -The tail sampler samples traces according to policies and the sampling decision of whether a trace should be sampled is determined at the _tail end_ of a pipeline. For more information on the supported policies and other configuration options of the sampler see [tail sampler configuration](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/tailsamplingprocessor/README). +The tail sampler samples traces according to policies and the sampling decision of whether a trace should be sampled is determined at the _tail end_ of a pipeline. For more information on the supported policies and other configuration options of the sampler see [tail sampler configuration](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/tailsamplingprocessor/README.md). The sampler waits for a certain amount of spans before making applying the configured policy. Due to it keeping a certain amount of spans in memory, the sampler incurs as slight performance cost compared to the probabilistic sampler. @@ -121,7 +121,7 @@ processors: }, { # Only keep 10% of the traces. - name: policy-probalistic, + name: policy-probabilistic, type: probabilistic, probabilistic: {sampling_percentage: 10} } @@ -136,7 +136,7 @@ service: ## Filtering traces -The bundled otel-collector also includes the [filter processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/filterprocessor/README). The following example only allows traces with the service name "foobar". All other traces will be dropped. +The bundled otel-collector also includes the [filter processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/filterprocessor/README.md). The following example only allows traces with the service name "foobar". All other traces will be dropped. ```yaml exporters: @@ -170,7 +170,7 @@ This section outlines some common exporter configurations. For details, see Open ### OTLP-compatible backends -Backends compatible with the [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp) include services such as: +Backends compatible with the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/) include services such as: - [Honeycomb](https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/) - [Grafana Tempo](https://grafana.com/blog/2021/04/13/how-to-send-traces-to-grafana-clouds-tempo-service-with-opentelemetry-collector/) @@ -179,24 +179,24 @@ OTLP-compatible backends typically accept the [OTLP gRPC protocol](#otlp-grpc-ba #### OTLP gRPC backends -Refer to the [otlp exporter](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README) documentation for available options. +Refer to the [otlp exporter](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlphttpexporter/README.md) documentation for available options. ```yaml exporters: otlp: - endpoint: otelcol2:4317 + endpoint: secure-otel-collector:4317 tls: cert_file: file.cert key_file: file.key otlp/2: - endpoint: otelcol2:4317 + endpoint: insecure-otel-collector:4317 tls: insecure: true ``` #### OTLP HTTP backends -Refer to the [otlphttp exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter/README) documentation for available options. +Refer to the [otlphttp exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter/README.md) documentation for available options. ```yaml exporters: @@ -208,7 +208,7 @@ exporters: If you're looking for information about Sourcegraph's bundled Jaeger instance, head back to the [Tracing](/admin/observability/tracing) page to find the instructions for your deployment method. -Refer to the [jaeger exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/jaegerexporter/README) documentation for options. +Refer to the [Jaeger](https://opentelemetry.io/docs/languages/js/exporters/#jaeger) documentation for options. If you must use your own Jaeger instance, and if the bundled otel-collector's basic configuration with the Jaeger OTel exporter enabled meets your needs, configure the otel-collector's startup command to `/bin/otelcol-sourcegraph --config=/etc/otel-collector/configs/jaeger.yaml`. Note that this requires the environment variable `$JAEGER_HOST` to be set on the otel-collector service / container: @@ -220,14 +220,13 @@ exporters: endpoint: "$JAEGER_HOST:14250" tls: insecure: true - -# Deployment environment variables: - ``` +The Sourcegraph frontend automatically proxies Jaeger's web UI to make it available at `/-/debug/jaeger`. You can proxy your own Jaeger instance instead by configuring the `JAEGER_SERVER_URL` environment variable on the `frontend` containers, and the `QUERY_BASE_PATH='/-/debug/jaeger'` environment variable on your `jaeger` container. + ### Google Cloud -If you run Sourcegraph in GCP and wish to export your HTTP traces to Google Cloud Trace, otel-collector can use project authentication. See the [googlecloud exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/googlecloudexporter/README) documentation for available options. +If you run Sourcegraph in GCP and wish to export your HTTP traces to Google Cloud Trace, otel-collector can use project authentication. See the [Google Cloud Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/googlecloudexporter/README.md) documentation for available options. ```yaml exporters: diff --git a/docs/admin/observability/tracing.mdx b/docs/admin/observability/tracing.mdx index 138db89d1..47829a4c9 100644 --- a/docs/admin/observability/tracing.mdx +++ b/docs/admin/observability/tracing.mdx @@ -23,11 +23,11 @@ To deploy our bundled Jaeger backend, follow the instructions for your deploymen Then configure your Site Configuration: 1. Ensure your `externalURL` is configured -2. Configure `urlTemplate` +2. Configure `observability.tracing` > `urlTemplate` 3. Optionally, configure `observability.client`, for Sourcegraph clients to also report traces, ex. src cli ```json - "externalURL": "https://your-sourcegraph-instance.example.com", + "externalURL": "https://sourcegraph.example.com", "observability.tracing": { "urlTemplate": "{{ .ExternalURL }}/-/debug/jaeger/trace/{{ .TraceID }}" }, @@ -43,22 +43,28 @@ Where: - `{{ .ExternalURL }}` is the value of the `externalURL` setting in your Sourcegraph instance's Site Configuration - `{{ .TraceID }}` is the TraceID which gets generated while processing the request -Once deployed, the Jaeger web UI will be accessible at `/-/debug/jaeger`. - -The Sourcegraph frontend automatically proxies Jaeger's web UI to make it available at `/-/debug/jaeger`. You can proxy your own Jaeger instance instead by configuring the `JAEGER_SERVER_URL` environment variable on the `frontend` containers, and the `QUERY_BASE_PATH='/-/debug/jaeger'` environment variable on your `jaeger` container. +Once deployed, the Jaeger web UI will be accessible at `/-/debug/jaeger` ### External OpenTelemetry-Compatible Platforms If you prefer to use an external, OTel-compatible platform, you can configure Sourcegraph to export traces to it instead. See our [OpenTelemetry documentation](/admin/observability/opentelemetry) for further details. -Once your OTel backend is configured, configure the `urlTemplate` to link to your tracing backend. +Then configure your Site Configuration: + +1. Configure `observability.tracing` > `urlTemplate` +2. Optionally, configure `observability.client`, for Sourcegraph clients to also report traces, ex. src cli -For example, if you [export your traces to Honeycomb](/admin/observability/opentelemetry#otlp-compatible-backends), your Site Configuration may look like: +For example, if you export your traces to [Honeycomb](/admin/observability/opentelemetry#otlp-compatible-backends), your Site Configuration may look like: ```json "observability.tracing": { "urlTemplate": "https://ui.honeycomb.io/YOUR-HONEYCOMB-ORG/environments/YOUR-HONEYCOMB-DATASET/trace?trace_id={{ .TraceID }}" - } + }, + "observability.client": { + "openTelemetry": { + "endpoint": "/-/debug/otlp" + } + }, ``` Where: From 58e4add627d287ffff60b42441220efd6cb92ff2 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc Date: Tue, 17 Dec 2024 18:51:18 -0700 Subject: [PATCH 3/4] Minor spelling changes --- docs/admin/deploy/kubernetes/azure.mdx | 4 ++-- docs/admin/deploy/kubernetes/configure.mdx | 2 +- docs/admin/deploy/kubernetes/index.mdx | 10 +++++----- docs/admin/deploy/kubernetes/kustomize.mdx | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/admin/deploy/kubernetes/azure.mdx b/docs/admin/deploy/kubernetes/azure.mdx index 4e0df7873..1bce0e9b7 100644 --- a/docs/admin/deploy/kubernetes/azure.mdx +++ b/docs/admin/deploy/kubernetes/azure.mdx @@ -1,7 +1,7 @@ # Sourcegraph with Kubernetes on Azure > WARNING: This guide applies exclusively to a Kubernetes deployment **without** Helm. -> If you have not deployed Sourcegraph yet, it is higly recommended to use Helm as it simplifies the configuration and greatly simplifies the later upgrade process. See our guidance on [using Helm to deploy to Azure AKS](/admin/deploy/kubernetes#configure-sourcegraph-on-azure-managed-kubernetes-service-aks). +> If you have not deployed Sourcegraph yet, it is highly recommended to use Helm as it simplifies the configuration and greatly simplifies the later upgrade process. See our guidance on [using Helm to deploy to Azure AKS](/admin/deploy/kubernetes#configure-sourcegraph-on-azure-managed-kubernetes-service-aks). Install the [Azure CLI tool](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) and log in: @@ -63,5 +63,5 @@ az aks browse --resource-group sourcegraphResourceGroup --name sourcegraphCluste Set up a load balancer to make the main web server accessible over the network to external users: ``` -kubectl expose deployment sourcegraph-frontend --type=LoadBalancer --name=sourcegraphloadbalancer --port=80 --target-port=3080 +kubectl expose deployment sourcegraph-frontend --type=LoadBalancer --name=sourcegraph-load-balancer --port=80 --target-port=3080 ``` diff --git a/docs/admin/deploy/kubernetes/configure.mdx b/docs/admin/deploy/kubernetes/configure.mdx index f7f97ea30..c66ec24ec 100644 --- a/docs/admin/deploy/kubernetes/configure.mdx +++ b/docs/admin/deploy/kubernetes/configure.mdx @@ -1137,7 +1137,7 @@ Sourcegraph will clone repositories using SSH credentials when the `id_rsa` and To mount the files through Kustomize: -**Step 1:** Copy the required files to the `configs` folder at the same level as your overylay's kustomization.yaml file +**Step 1:** Copy the required files to the `configs` folder at the same level as your overlay's kustomization.yaml file **Step 2:** Include the following in your overlay to [generate secrets](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/) that base64 encoded the values in those files diff --git a/docs/admin/deploy/kubernetes/index.mdx b/docs/admin/deploy/kubernetes/index.mdx index f7eb3c910..3809a4fa2 100644 --- a/docs/admin/deploy/kubernetes/index.mdx +++ b/docs/admin/deploy/kubernetes/index.mdx @@ -156,12 +156,12 @@ Although not recommended, credentials can also be configured directly in the hel ```yaml pgsql: - enabled: false # disable internal pgsql database + enabled: false # Disable internal pgsql database auth: - database: "customdb" - host: pgsql.database.company.com # external pgsql host - user: "newuser" - password: "newpassword" + database: "custom-db" + host: pgsql.database.company.com # External pgsql host + user: "new-user" + password: "new-password" port: "5432" ``` diff --git a/docs/admin/deploy/kubernetes/kustomize.mdx b/docs/admin/deploy/kubernetes/kustomize.mdx index caeda43fd..c48893640 100644 --- a/docs/admin/deploy/kubernetes/kustomize.mdx +++ b/docs/admin/deploy/kubernetes/kustomize.mdx @@ -85,7 +85,7 @@ A storage class must be created and configured before deploying Sourcegraph. SSD #### Option 1: Create a new storage class -We recommend using a preconfigured storage class component for your cloud provider if you can create cluster-wide resources: +We recommend using a pre-configured storage class component for your cloud provider if you can create cluster-wide resources: ```yaml # instances/my-sourcegraph/kustomization.yaml From 13596ddc1c8e965a0910ff78e2a5024e3ed2993e Mon Sep 17 00:00:00 2001 From: Marc LeBlanc Date: Tue, 17 Dec 2024 18:54:27 -0700 Subject: [PATCH 4/4] Fixing incorrect link --- docs/admin/observability/opentelemetry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/observability/opentelemetry.mdx b/docs/admin/observability/opentelemetry.mdx index b7fe8c7fe..34b100dd6 100644 --- a/docs/admin/observability/opentelemetry.mdx +++ b/docs/admin/observability/opentelemetry.mdx @@ -179,7 +179,7 @@ OTLP-compatible backends typically accept the [OTLP gRPC protocol](#otlp-grpc-ba #### OTLP gRPC backends -Refer to the [otlp exporter](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlphttpexporter/README.md) documentation for available options. +Refer to the [otlp exporter](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README.md) documentation for available options. ```yaml exporters: