docs and comments

Author: VihasMakwana

internal/pkg/otel/elasticdiagnosticsextension/README.md

@@ -0,0 +1,37 @@
+# elasticdiagnosticsextension
+
+`elasticdiagnosticsextension` is an internal package for peforming diagnostics and is used in conjunction with EDOT:
+
+## Features
+
+- Acts as a registrar and keeps track of common diagnostic hooks.
+- Collects profiles using `runtime/pprof`.
+- Collects internal telemetry exposed by the OTeL Collector.
+- Implements the `extensioncapabilities.ConfigWatcher` interface and stores the latest configuration of the running collector.
+- Listens for diagnostic requests and provides diagnostic data. 
+
+## Design
+
+### Diagnostic hooks:
+- Individual beats register custom diagnostic hooks and these hooks are called when we run the elastic-agent diagnostics command.
+- Our extension stores these hooks and executes them everytime it gets a "diagnostics" request.
+
+### Request/Response format:
+- This extension runs an HTTP server and listens to new requests on `/diagnostics` path.
+- It doesn't expect any requets params or body.
+- The response format is defined in [response.go](./response.go). 
+    - `GlobalDiagnostics`: Data related to the overall process:
+        1. Profiles.
+        2. Internal telemetry.
+        3. latest collector configuration.
+    - `ComponentDiagnostics`: Data from individual receivers, collected via registered diagnostic hooks.
+
+### Interaction with Elastic-Agent service in hybrid mode.
+
+- When the user triggers the diagnostic request, EDOT diagnostics are injected at two levels:
+    1. At top-Level:
+        - When `DiagnosticAgent()` is called in [server.go](https://github.com/elastic/elastic-agent/blob/710c49f45433e2f136a6e41cae980c1aa37dabdd/pkg/control/v2/server/server.go#L197).
+        - Diagnostics are captured at the global level and stored under the `edot/*` directory in the resulting ZIP archive.
+    2. At component-level:
+        - When `otelMgr.PerformComponentsDiagnostics()` is called in [coordinator.go](https://github.com/elastic/elastic-agent/blob/710c49f45433e2f136a6e41cae980c1aa37dabdd/internal/pkg/agent/application/coordinator/coordinator.go#L863).
+        - Diagnostics are added per component and stored under the `components/{comp}/*` directory in the resulting ZIP archive.

internal/pkg/otel/elasticdiagnosticsextension/extension.go

@@ -9,7 +9,6 @@ import (
 	"net"
 	"net/http"
 	"os"
-	"runtime"
 	"runtime/pprof"
 	"strconv"
 	"sync"
@@ -45,7 +44,9 @@ type diagnosticsExtension struct {
 	collectorConfig   *confmap.Conf
 	componentHooks    map[string][]*diagHook
 	globalHooks       map[string]*diagHook
-	hooksMtx          sync.Mutex
+
+	hooksMtx sync.Mutex
+	confgMtx sync.Mutex
 }
 
 type serviceConfig struct {
@@ -156,6 +157,8 @@ func (d *diagnosticsExtension) Shutdown(ctx context.Context) error {
 }
 
 func (d *diagnosticsExtension) NotifyConfig(ctx context.Context, conf *confmap.Conf) error {
+	d.confgMtx.Lock()
+	defer d.confgMtx.Unlock()
 	d.collectorConfig = conf
 	return nil
 }
@@ -237,12 +240,3 @@ func extractMetricAddress(readers []otelconf.MetricReader) string {
 	}
 	return ""
 }
-
-func changeOwner(path string, uid, gid int) error {
-	if runtime.GOOS == "windows" {
-		// on windows it always returns the syscall.EWINDOWS error, wrapped in *PathError
-		return nil
-	}
-
-	return os.Chown(path, uid, gid)
-}

internal/pkg/otel/manager/diagnostics.go

@@ -164,11 +164,14 @@ func (m *OTelManager) PerformComponentDiagnostics(
 
 	extDiagnostics, err := otel.PerformDiagnosticsExt()
 	if errors.Is(err, syscall.ENOENT) || errors.Is(err, syscall.ECONNREFUSED) {
+		// We're not running the EDOT if:
+		//  1. Either the socket doesn't exist
+		//	2. It is refusing the connections.
+		m.logger.Debugf("Couldn't fetch diagnostics from EDOT: %v", err)
 		return diagnostics, nil
 	}
 	if err != nil {
-		m.logger.Errorf("error fetching diagnostics: %v", err)
-		return nil, err
+		return nil, fmt.Errorf("error fetching otel diagnostics: %w", err)
 	}
 
 	for idx, diag := range diagnostics {