docs (receiver/k8slog): describe detailed design for each mode.

receiver/k8slogreceiver/design.md

@@ -26,4 +26,95 @@ API ────┐ │ │
 
 The `Source` will get information about pods from the Kubernetes API and will get the paths will log files exist from the Docker API and the CRI API (Only containerd is supported now).
 
-Then, the files will be found and read by the `Poller` and `Reader`.
+Then, the files will be found and read by the `Poller` and `Reader`.
+
+More detailed, for the three mode, the design is as follows:
+
+## daemonset-stdout
+
+```
+ k8sapi     ┌──────────────┐    docker/cri-containerd
+   │        │              │             │
+   └───────▶│    Source    │◀────────────┘
+  medatada  │              │ logPath, env
+            └──────────────┘
+                  │ assosiate
+                  ▼
+            ┌──────────────┐
+            │   Reader     │
+            └──────────────┘
+                  │ read files from logPath
+                  ▼
+                files
+```
+
+The `Source` will get pod list and metadata from k8s api (maybe there will also be an implementation using kubelet).
+Then, it will get the logPath and env from docker/cri-containerd api. And they will be associated with the pod metadata
+by `container.id`.
+Finally, there will be a Reader to read the files from logPath.
+
+## daemonset-file
+
+```
+  k8sapi     ┌──────────────┐    docker/cri-containerd
+    │        │              │             │
+    └───────▶│    Source    │◀────────────┘
+   medatada  │              │ graph driver, 
+             │              │ mount points, env
+             └──────────────┘
+                  │ assosiate
+                  ▼
+              ┌──────────────┐
+              │   Poller     │ find files based on includes mount point.
+              └──────────────┘
+                  │ create
+                  ▼
+              ┌──────────────┐
+              │   Reader     │
+              └──────────────┘
+                  │ read files
+                  ▼
+                 files
+```
+
+As same as `deamonset-stdout`, the `Source` will get pod list and metadata from k8s api (maybe there will also be an
+implementation using kubelet).
+Then, it will get the graph driver (to get mount point of `/`), and mount points, so the actual path of log files cloud
+be calculated.
+Then, the `Poller` will find the files based on the includes mount point. And the `Reader` will read the files from
+logPath.
+
+For example, for a docker container, which has the following mount points:
+
+- / -> /var/lib/docker/overlay2/xxxxxxxxxxxxx/merged, where the newly generated files are under
+  /var/lib/docker/overlay2/xxxxxxxxxxxxx/upper
+- /logs -> /home/xxx/logs/
+
+The first one is caculated by the graph driver, and the second one is from the mount points.
+
+Also, the host root is mounted under /host-root on the otel container.
+
+Then, when the user configures `include=["/logs/*.log", "/var/log/*.log"]`, we can find log files by
+`/host-root/home/xxx/logs/*.log` and `/host-root/var/lib/docker/overlay2/xxxxxxxxxxxxx/upper/var/log/*.log`.
+If symbolic links are involved, we need to recursively perform the above mount-point-based mapping process on the target
+of the link according to the mount point.
+
+## sidecar
+
+```
+            ┌──────────────┐
+  env ───▶  │   Poller     │ find files based on include from config
+            └──────────────┘
+                │ create
+                ▼
+            ┌──────────────┐
+            │   Reader     │
+            └──────────────┘
+                │ read files
+                ▼
+               files
+```
+
+This mode is similar to `filelog` receiver.
+The main special feature planed is to convinentlly get k8s metadata and env from the pod.
+More special features for k8s may be added in the future.

receiver/k8slogreceiver/go.mod

@@ -5,10 +5,10 @@ go 1.21
 require (
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/k8sconfig v0.96.0
 	github.com/stretchr/testify v1.9.0
-	go.opentelemetry.io/collector/component v0.96.0
-	go.opentelemetry.io/collector/confmap v0.96.0
-	go.opentelemetry.io/collector/consumer v0.96.0
-	go.opentelemetry.io/collector/receiver v0.96.0
+	go.opentelemetry.io/collector/component v0.96.1-0.20240315172937-3b5aee0c7a16
+	go.opentelemetry.io/collector/confmap v0.96.1-0.20240315172937-3b5aee0c7a16
+	go.opentelemetry.io/collector/consumer v0.96.1-0.20240315172937-3b5aee0c7a16
+	go.opentelemetry.io/collector/receiver v0.96.1-0.20240315172937-3b5aee0c7a16
 	go.opentelemetry.io/otel/metric v1.24.0
 	go.opentelemetry.io/otel/trace v1.24.0
 	go.uber.org/multierr v1.11.0
@@ -27,7 +27,7 @@ require (
 	github.com/go-openapi/swag v0.22.3 // indirect
 	github.com/go-viper/mapstructure/v2 v2.0.0-alpha.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/gnostic-models v0.6.8 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
@@ -65,14 +65,14 @@ require (
 	golang.org/x/time v0.4.0 // indirect
 	google.golang.org/appengine v1.6.8 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240123012728-ef4313101c80 // indirect
-	google.golang.org/grpc v1.62.0 // indirect
-	google.golang.org/protobuf v1.32.0 // indirect
+	google.golang.org/grpc v1.62.1 // indirect
+	google.golang.org/protobuf v1.33.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/api v0.29.2 // indirect
-	k8s.io/apimachinery v0.29.2 // indirect
-	k8s.io/client-go v0.29.2 // indirect
+	k8s.io/api v0.29.3 // indirect
+	k8s.io/apimachinery v0.29.3 // indirect
+	k8s.io/client-go v0.29.3 // indirect
 	k8s.io/klog/v2 v2.110.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20231010175941-2dd684a91f00 // indirect
 	k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect