docs(profiling): update guide for OTel migration

Replace the obsolete profiling.enable ConfigMap key with
runtime-profiling (enabled/disabled). Remove the K_METRICS_CONFIG
controller section since the controller now uses ConfigMap-based
observability via the eventing adapter. Document that controller
profiling requires a pod restart as the adapter reads config once
at startup. Add CONFIG_OBSERVABILITY_NAME prerequisite for the
webhook.

Fixes #2633

Signed-off-by: Akshay Pant <akpant@redhat.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: theakshaypant

docs/content/docs/operations/profiling.md

@@ -31,98 +31,69 @@ When profiling is disabled the server still listens but returns `404` for every
 
 ## Enabling Profiling
 
-### Watcher
-
-The **watcher** (`pipelines-as-code-watcher`) uses Knative's `sharedmain` framework,
-which watches the `config-observability` ConfigMap and toggles profiling **without a
-restart**.
-
-**`PAC_DISABLE_HEALTH_PROBE=true` must be set on the watcher, otherwise a port conflict
-on 8080 will cause the profiling server to shut down:**
-
-```bash
-kubectl set env deployment/pipelines-as-code-watcher \
-  -n pipelines-as-code \
-  PAC_DISABLE_HEALTH_PROBE=true
-```
-
-Then enable profiling via the ConfigMap:
+All components read profiling configuration from the same ConfigMap:
 
 ```bash
+# Enable
 kubectl patch configmap pipelines-as-code-config-observability \
   -n pipelines-as-code \
   --type merge \
-  -p '{"data":{"profiling.enable":"true"}}'
-```
+  -p '{"data":{"runtime-profiling":"enabled"}}'
 
-To disable profiling:
-
-```bash
+# Disable
 kubectl patch configmap pipelines-as-code-config-observability \
   -n pipelines-as-code \
   --type merge \
-  -p '{"data":{"profiling.enable":"false"}}'
+  -p '{"data":{"runtime-profiling":"disabled"}}'
 ```
 
-The watcher picks up the ConfigMap change immediately without a restart.
-
-### Webhook
+### Component-specific prerequisites
 
-The **webhook** (`pipelines-as-code-webhook`) also uses `sharedmain` and supports
-dynamic toggling via the same ConfigMap. Unlike the watcher, the webhook does not run
-its own health probe server, so `PAC_DISABLE_HEALTH_PROBE` is not required.
+| Component | Extra step required |
+| --- | --- |
+| **watcher** | Set `PAC_DISABLE_HEALTH_PROBE=true` — otherwise a port conflict on 8080 causes the profiling server to shut down (see below). Picks up ConfigMap changes without a restart. |
+| **controller** | Profiling must be enabled in the ConfigMap **before** the pod starts — a pod restart is required after any change. The eventing adapter framework reads the profiling config once at startup and does not watch for ConfigMap updates. |
+| **webhook** | Set `CONFIG_OBSERVABILITY_NAME=pipelines-as-code-config-observability` — the webhook Deployment does not set this by default and falls back to `config-observability`, which does not exist in the PAC namespace. Picks up ConfigMap changes without a restart. |
 
-The webhook deployment does not set `CONFIG_OBSERVABILITY_NAME` by default, so it
-falls back to looking for a ConfigMap named `config-observability`, which does not
-exist in the PAC namespace. Set the environment variable first:
+For the watcher:
 
 ```bash
-kubectl set env deployment/pipelines-as-code-webhook \
+kubectl set env deployment/pipelines-as-code-watcher \
   -n pipelines-as-code \
-  CONFIG_OBSERVABILITY_NAME=pipelines-as-code-config-observability
+  PAC_DISABLE_HEALTH_PROBE=true
 ```
 
-Then use the same `kubectl patch` on the ConfigMap above to enable or disable profiling.
-
-### Controller
-
-The **controller** (`pipelines-as-code-controller`) uses the Knative eventing adapter
-framework. Profiling is configured at startup from the `K_METRICS_CONFIG` environment
-variable and is **not** dynamically reloaded; a pod restart is required after any change.
-
-The `K_METRICS_CONFIG` variable contains a JSON object whose `ConfigMap` field holds
-inline key/value configuration data. To enable profiling, add `"profiling.enable":"true"`
-inside that `ConfigMap` object:
+For the webhook:
 
 ```bash
-# Read the current value first
-kubectl get deployment pipelines-as-code-controller \
+kubectl set env deployment/pipelines-as-code-webhook \
   -n pipelines-as-code \
-  -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="K_METRICS_CONFIG")].value}'
+  CONFIG_OBSERVABILITY_NAME=pipelines-as-code-config-observability
 ```
 
-Then patch the Deployment with `profiling.enable` added to the `ConfigMap` field, for example:
+## Accessing Profiles
+
+The profiling server listens on port **8008** by default. If that conflicts with another
+service, set `PROFILING_PORT` on the relevant Deployment(s) before proceeding:
 
 ```bash
-kubectl set env deployment/pipelines-as-code-controller \
+kubectl set env deployment/pipelines-as-code-watcher \
+  deployment/pipelines-as-code-controller \
+  deployment/pipelines-as-code-webhook \
   -n pipelines-as-code \
-  'K_METRICS_CONFIG={"Domain":"pipelinesascode.tekton.dev/controller","Component":"pac_controller","PrometheusPort":9090,"ConfigMap":{"name":"pipelines-as-code-config-observability","profiling.enable":"true"}}'
+  PROFILING_PORT=8090
 ```
 
-This triggers a rolling restart of the controller pod. Remove `"profiling.enable":"true"`
-(or set it to `"false"`) and re-apply to disable.
-
-## Accessing Profiles
-
-Port 8008 is not declared in the container spec by default. To make it reachable, patch
-the target Deployment(s) to add the port:
+Port 8008 (or your chosen port) is not declared in the container spec by default. Patch
+the target Deployment(s) to expose it — substituting the port number if you changed it:
 
 ```bash
+PROFILING_PORT=8008  # change if you set a custom port above
 for deploy in pipelines-as-code-watcher pipelines-as-code-controller pipelines-as-code-webhook; do
   kubectl patch deployment "$deploy" \
     -n pipelines-as-code \
     --type json \
-    -p '[{"op":"add","path":"/spec/template/spec/containers/0/ports/-","value":{"name":"profiling","containerPort":8008,"protocol":"TCP"}}]'
+    -p "[{\"op\":\"add\",\"path\":\"/spec/template/spec/containers/0/ports/-\",\"value\":{\"name\":\"profiling\",\"containerPort\":${PROFILING_PORT},\"protocol\":\"TCP\"}}]"
 done
 ```
 
@@ -155,27 +126,14 @@ export POD_NAME=$(kubectl get pods -n pipelines-as-code \
   -o jsonpath='{.items[0].metadata.name}')
 ```
 
-Then, forward a local port to the pod's profiling port:
+Then, forward a local port to the pod's profiling port (adjust if you changed `PROFILING_PORT`):
 
 ```bash
 kubectl port-forward -n pipelines-as-code $POD_NAME 8008:8008
 ```
 
 The pprof index is now available at `http://localhost:8008/debug/pprof/`.
 
-### Changing the profiling port
-
-If port 8008 conflicts with another service, set the `PROFILING_PORT` environment
-variable on the Deployment to use a different port:
-
-```bash
-kubectl set env deployment/pipelines-as-code-watcher \
-  -n pipelines-as-code \
-  PROFILING_PORT=8090
-```
-
-Update the `containerPort` in the patch above and your port-forward command to match.
-
 ### Capturing profiles with `go tool pprof`
 
 With `kubectl port-forward` running, use `go tool pprof` to analyze profiles directly:
@@ -214,4 +172,4 @@ in the container spec by default, access requires an explicit Deployment patch,
 it to users with `deployments/patch` permission in the `pipelines-as-code` namespace.
 
 Do not expose port 8008 via a Service or Ingress in production environments. Disable
-profiling (`profiling.enable: "false"`) when not actively investigating an issue.
+profiling (`runtime-profiling: "disabled"`) when not actively investigating an issue.