Add EDOT narrative docs

.github/workflows/update-kube-stack-version.yml

@@ -0,0 +1,65 @@
+name: Update Kube-Stack Version
+
+on:
+  schedule:
+    # Run every Monday at 9:00 AM UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  update-kube-stack-version:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+
+    - name: Run kube-stack version update script
+      run: |
+        cd scripts
+        python update_kube_stack_version.py
+
+    - name: Check for changes
+      id: verify-changed-files
+      run: |
+        if [ -n "$(git status --porcelain)" ]; then
+          echo "changed=true" >> $GITHUB_OUTPUT
+        else
+          echo "changed=false" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Commit and push changes
+      if: steps.verify-changed-files.outputs.changed == 'true'
+      run: |
+        git config --local user.email "[email protected]"
+        git config --local user.name "GitHub Action"
+        git add docs/docset.yml
+        git commit -m "chore: update kube-stack version [skip ci]"
+        git push
+
+    - name: Create Pull Request
+      if: steps.verify-changed-files.outputs.changed == 'true'
+      uses: peter-evans/create-pull-request@v5
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        commit-message: "chore: update kube-stack version"
+        title: "chore: update kube-stack version"
+        body: |
+          This PR automatically updates the kube-stack version in `docs/docset.yml` based on the latest version from the elastic-agent repository.
+
+          **Changes:**
+          - Updated kube-stack version in docset.yml
+
+          This PR was created automatically by the weekly kube-stack version update workflow.
+        branch: update-kube-stack-version
+        delete-branch: true
+        labels: |
+          automated
+          documentation

docset.yml

@@ -1,3 +1,3 @@
 project: 'Elastic documentation'
 max_toc_depth: 2
 
@@ -297,3 +297,4 @@
   ece-apis: https://www.elastic.co/docs/api/doc/cloud-enterprise/
   intake-apis: https://www.elastic.co/docs/api/doc/observability-serverless/
   models-app: "Trained Models"
+  kube-stack-version: 0.6.3

scripts/update_kube_stack_version.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""
+Kube-Stack Version Update Script
+
+This script automatically updates the kube-stack version in the docset.yml file
+by fetching the latest version from the elastic-agent repository.
+
+Usage:
+    python update_kube_stack_version.py [--dry-run]
+
+Options:
+    --dry-run    Show what would be updated without making changes
+"""
+
+import urllib.request
+import re
+import sys
+import argparse
+from pathlib import Path
+
+
+def fetch_url_content(url):
+    """Fetch content from a URL"""
+    try:
+        print(f"Attempting to fetch: {url}")
+        with urllib.request.urlopen(url) as response:
+            content = response.read().decode('utf-8')
+        return content
+    except urllib.error.URLError as e:
+        print(f"Failed to retrieve content: {e.reason}")
+        return None
+
+
+def get_collector_version(file_path):
+    """Extract the collector version from docset.yml"""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as file:
+            content = file.read()
+
+        lines = content.splitlines()
+        for line in lines:
+            if line.strip().startswith('edot-collector-version:'):
+                return line.split(':', 1)[1].strip()
+
+        # If no specific version is found, use a default version that we know works
+        return '9.1.2'
+    except FileNotFoundError:
+        print(f"Error: Could not find {file_path}")
+        return None
+    except Exception as e:
+        print(f"Error reading {file_path}: {e}")
+        return None
+
+
+def get_kube_stack_version(version='main'):
+    """Extract KubeStackChartVersion from elastic-agent repository"""
+    # Try different URL formats for the k8s.go file
+    # First try with the version as-is (in case it already has 'v' prefix)
+    url = f'https://raw.githubusercontent.com/elastic/elastic-agent/{version}/testing/integration/k8s/k8s.go'
+    print(f"Trying k8s.go URL: {url}")
+    content = fetch_url_content(url)
+
+    # If first attempt fails and version doesn't start with 'v', try with 'v' prefix
+    if content is None and not version.startswith('v') and version != 'main':
+        url = f'https://raw.githubusercontent.com/elastic/elastic-agent/v{version}/testing/integration/k8s/k8s.go'
+        print(f"Retrying k8s.go with URL: {url}")
+        content = fetch_url_content(url)
+
+    # If that fails too, try with main branch
+    if content is None:
+        url = 'https://raw.githubusercontent.com/elastic/elastic-agent/main/testing/integration/k8s/k8s.go'
+        print(f"Falling back to main branch for k8s.go: {url}")
+        content = fetch_url_content(url)
+
+    if content is None:
+        print(f"Could not fetch k8s.go from any URL")
+        return None
+
+    # Look for the KubeStackChartVersion line
+    lines = content.splitlines()
+    for line in lines:
+        if 'KubeStackChartVersion' in line and '=' in line:
+            # Extract the version from the line like: KubeStackChartVersion = "0.6.3"
+            match = re.search(r'KubeStackChartVersion\s*=\s*"([^"]+)"', line)
+            if match:
+                return match.group(1)
+
+    print("Could not find KubeStackChartVersion in k8s.go")
+    return None
+
+
+def update_docset_kube_stack_version(version, docset_path, dry_run=False):
+    """Update the kube-stack-version substitution in docset.yml"""
+    try:
+        with open(docset_path, 'r', encoding='utf-8') as file:
+            content = file.read()
+
+        # Replace the kube-stack-version line
+        pattern = r'(kube-stack-version:\s*)[0-9]+\.[0-9]+\.[0-9]+'
+        replacement = f'\\g<1>{version}'
+        new_content = re.sub(pattern, replacement, content)
+
+        if new_content != content:
+            if dry_run:
+                print(f"[DRY RUN] Would update kube-stack-version to {version} in {docset_path}")
+                return True
+            else:
+                with open(docset_path, 'w', encoding='utf-8') as file:
+                    file.write(new_content)
+                print(f"Updated kube-stack-version to {version} in {docset_path}")
+                return True
+        else:
+            print(f"kube-stack-version already up to date: {version}")
+            return False
+
+    except Exception as e:
+        print(f"Error updating {docset_path}: {e}")
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Update kube-stack version in docset.yml')
+    parser.add_argument('--dry-run', action='store_true', 
+                       help='Show what would be updated without making changes')
+    args = parser.parse_args()
+
+    # Get the script directory and construct paths relative to it
+    script_dir = Path(__file__).parent
+    docset_path = script_dir.parent / 'docset.yml'
+
+    print(f"Using docset.yml path: {docset_path}")
+
+    # Get the current collector version from docset.yml
+    col_version = get_collector_version(docset_path)
+    if col_version is None:
+        print("Error: Could not determine collector version")
+        sys.exit(1)
+
+    print(f"Collector version: {col_version}")
+
+    # Get the kube-stack version from elastic-agent repository
+    kube_stack_version = get_kube_stack_version(col_version)
+    if kube_stack_version is None:
+        print("Error: Could not fetch kube-stack version")
+        sys.exit(1)
+
+    print(f"Found kube-stack version: {kube_stack_version}")
+
+    # Update the docset.yml file
+    success = update_docset_kube_stack_version(kube_stack_version, docset_path, args.dry_run)
+
+    if success:
+        print("Kube-stack version update completed successfully")
+        sys.exit(0)
+    else:
+        print("No update was needed or update failed")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

solutions/_snippets/obs-apm-project.md

@@ -5,7 +5,7 @@ Bring traces, logs, and metrics into Elastic APM to help you troubleshoot and op
 ::::{tab-set}
 :::{tab-item} OpenTelemetry
 
-The [Elastic Distribution of OpenTelemetry (EDOT) SDKs](opentelemetry://reference/edot-sdks/index.md) facilitate the collection of traces, metrics, and logs in OpenTelemetry format into Elastic APM.
+The [Elastic Distribution of OpenTelemetry (EDOT) SDKs](opentelemetry:/opentelemetry://reference/edot-sdks/index.md) facilitate the collection of traces, metrics, and logs in OpenTelemetry format into Elastic APM.
 
 1. Select **Add data** from the main menu and then select **Application**.
 2. Select **OpenTelemetry**.

solutions/observability/apm/collect-application-data.md

@@ -21,7 +21,7 @@ products:
 
 Use Elastic APM agents or an OpenTelemetry language SDK to instrument a service in the language its written in:
 
-* [**OpenTelemetry**](/solutions/observability/apm/use-opentelemetry-with-apm.md): OpenTelemetry is an open source set of APIs, SDKs, tooling, and integrations that enable the capture and management of telemetry data from your services and applications. Elastic offers [Elastic Distributions of OpenTelemetry (EDOT)](opentelemetry://reference/edot-sdks/index.md), which are customized versions of [OpenTelemetry language SDKs](https://opentelemetry.io/docs/languages/) that are optimized to work with an Elastic backend.
+* [**OpenTelemetry**](/solutions/observability/apm/use-opentelemetry-with-apm.md): OpenTelemetry is an open source set of APIs, SDKs, tooling, and integrations that enable the capture and management of telemetry data from your services and applications. Elastic offers [Elastic Distributions of OpenTelemetry (EDOT)](opentelemetry:/opentelemetry://reference/edot-sdks/index.md), which are customized versions of [OpenTelemetry language SDKs](https://opentelemetry.io/docs/languages/) that are optimized to work with an Elastic backend.
 * [**Elastic APM agents**](/solutions/observability/apm/elastic-apm-agents.md): Elastic APM agents are instrumentation libraries written in the same language as your service.
 
 

solutions/observability/apm/use-opentelemetry-with-apm.md

@@ -23,7 +23,7 @@ Elastic offers several distributions of OpenTelemetry. Each [Elastic Distributio
 
 ## Why use the Elastic Distributions of OpenTelemetry?
 
-With an [Elastic Distribution of OpenTelemetry language SDK](opentelemetry://reference/edot-sdks/index.md) you have access to all the features of the OpenTelemetry SDK that it customizes, plus:
+With an [Elastic Distribution of OpenTelemetry language SDK](opentelemetry:/opentelemetry://reference/edot-sdks/index.md) you have access to all the features of the OpenTelemetry SDK that it customizes, plus:
 
 * You can get access to SDK improvements and bug fixes contributed by the Elastic team before the changes are available in the OpenTelemetry repositories.
 * The distribution configures the collection of tracing and metrics signals, applying opinionated defaults, such as which sources are collected by default.

solutions/observability/applications/llm-observability.md

@@ -33,11 +33,11 @@ You can instrument the application with one of the following Elastic Distributio
 - [Node.js](https://github.com/elastic/elastic-otel-node)
 - [Java](https://github.com/elastic/elastic-otel-java)
 
-EDOT includes many types of LLM instrumentation. This [table](opentelemetry://reference/use-cases/llms/index.md#supported-technologies) lists the supported technologies.
+EDOT includes many types of LLM instrumentation. This [table](opentelemetry://solutions/observability/get-started/opentelemetry/use-cases/llms/index.md#supported-technologies) lists the supported technologies.
 
 ### Getting started
 
-Check [these instructions](opentelemetry://reference/use-cases/llms/index.md) on how to setup and collect OpenTelemetry data for your LLM applications.
+Check [these instructions](opentelemetry://solutions/observability/get-started/opentelemetry/use-cases/llms/index.md) on how to setup and collect OpenTelemetry data for your LLM applications.
 
 ## Use cases
 

solutions/observability/get-started/opentelemetry/_snippets/edot-collector-auth.md

@@ -0,0 +1,22 @@
+```yaml
+extensions:
+  bearertokenauth:
+    scheme: "APIKey"
+    token: "<ENCODED_ELASTICSEARCH_APIKEY>"
+
+  apmconfig:
+    opamp:
+      protocols:
+        http:
+          # Default is localhost:4320
+          # endpoint: "<CUSTOM_OPAMP_ENDPOINT>"
+    source:
+      elasticsearch:
+        endpoint: "<ELASTICSEARCH_ENDPOINT>"
+        auth:
+          authenticator: bearertokenauth
+```
+
+:::{note}
+For comprehensive authentication configuration options, see [Authentication methods](/reference/edot-collector/config/authentication-methods.md).
+:::

solutions/observability/get-started/opentelemetry/_snippets/guided-instructions.md

@@ -0,0 +1,6 @@
+Use the **Add data** screen in Elastic Observability to generate install commands that are already configured with the values you need.
+
+1. Open Elastic Observability.
+2. Go to **Add data**.
+3. Select what you want to monitor.
+4. Follow the instructions.

solutions/observability/get-started/opentelemetry/_snippets/process-config.md

@@ -0,0 +1,17 @@
+Process metrics are turned off by default to avoid generating a large volume of timeseries data. To turn on process metrics, uncomment or add the following section inside the `hostmetrics` receiver configuration:
+
+```yaml
+  process:
+     mute_process_exe_error: true
+     mute_process_io_error: true
+     mute_process_user_error: true
+     metrics:
+        process.threads:
+        enabled: true
+        process.open_file_descriptors:
+        enabled: true
+        process.memory.utilization:
+        enabled: true
+        process.disk.operations:
+        enabled: true
+```

solutions/observability/get-started/opentelemetry/_snippets/retrieve-credentials.md

@@ -0,0 +1,9 @@
+Retrieve your {{es}} URL and your API key:
+
+1. Retrieve the {{es}} URL for your {{ecloud}} deployment:
+
+    1. Go to the [{{ecloud}} console](https://cloud.elastic.co/).
+    2. Next to your deployment, select **Manage**.
+    3. Under **Applications** next to **{{es}}**, select **Copy endpoint**.
+
+2. Create an API Key following [these instructions](/deploy-manage/api-keys/elasticsearch-api-keys.md).

solutions/observability/get-started/opentelemetry/_snippets/serverless-endpoint-api.md

@@ -0,0 +1,7 @@
+Follow these steps to retrieve the managed OTLP endpoint URL for your Serverless project:
+
+1. In {{serverless-full}}, open your Observability project.
+2. Go to **Add data** → **Application** → **OpenTelemetry**.
+3. Select **Managed OTLP Endpoint** in the second step.
+4. Copy the OTLP endpoint configuration value.
+5. Select **Create API Key** to generate an API key.