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

deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md

@@ -111,7 +111,7 @@ This table compares Observability capabilities between {{ech}} deployments and O
 | **APM integration** | ✅ | ✅ | Use **Managed Intake Service** (supports Elastic APM and OTLP protocols) <br> Refer to [Managed OTLP endpoint](opentelemetry://reference/motlp.md) for OTLP data ingestion |
 | [**APM Agent Central Configuration**](/solutions/observability/apm/apm-agent-central-configuration.md) | ✅ | ❌ | Not available in Serverless |
 | [**APM Tail-based sampling**](/solutions/observability/apm/transaction-sampling.md#apm-tail-based-sampling) | ✅ | ❌ | - Not available in Serverless <br>- Consider **OpenTelemetry** tail sampling processor as an alternative |
-| [**Android agent/SDK instrumentation**](opentelemetry://reference/edot-sdks/android/index.md) | ✅ | ✅ | |
+| [**Android agent/SDK instrumentation**](apm-agent-android://reference/edot-android/index.md) | ✅ | ✅ | |
 | [**AWS Firehose integration**](/solutions/observability/cloud/monitor-amazon-web-services-aws-with-amazon-data-firehose.md) | ✅ | ✅ | |
 | [**Custom roles for Kibana Spaces**](/deploy-manage/manage-spaces.md#spaces-control-user-access) | ✅ | ✅ | |
 | [**Data stream lifecycle**](/manage-data/lifecycle/data-stream.md) | ✅ | ✅ | Primary lifecycle management method in Serverless |
@@ -121,7 +121,7 @@ This table compares Observability capabilities between {{ech}} deployments and O
 | **[Fleet Agent policies](/reference/fleet/agent-policy.md)** | ✅ | ✅ | |
 | **[Fleet server](/reference/fleet/fleet-server.md)** | - Self-hosted <br>- Hosted | ✅ | Fully managed by Elastic |
 | [**Index lifecycle management**](/manage-data/lifecycle/index-lifecycle-management.md) | ✅ | ❌ | Use [**Data stream lifecycle**](/manage-data/lifecycle/data-stream.md) instead |
-| **[iOS agent/SDK instrumentation](opentelemetry://reference/edot-sdks/ios/index.md)** | ✅ | ✅ | |
+| **[iOS agent/SDK instrumentation](apm-agent-ios://reference/edot-ios/index.md)** | ✅ | ✅ | |
 | **[Kibana Alerts](/deploy-manage/monitor/monitoring-data/configure-stack-monitoring-alerts.md)** | ✅ | ✅ | |
 | **[LogsDB index mode](/manage-data/data-store/data-streams/logs-data-stream.md)** | ✅ | ✅ | - Reduces storage footprint <br> - Enabled by default <br>- Cannot be disabled |
 | **[Logs management](/solutions/observability/logs.md)** | ✅ | ✅ | |

docset.yml

@@ -294,3 +294,4 @@ subs:
   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/observability/apm/api-keys.md

@@ -151,10 +151,10 @@ To view all API keys for your project:
 
 You can now apply your newly created API keys in the configuration of each of your APM agents. See the relevant agent documentation for additional information:
 
-* **Android**: [`apiKey`](opentelemetry://reference/edot-sdks/android/configuration.md)
+* **Android**: [`apiKey`](apm-agent-android://reference/edot-android/configuration.md)
 * **Go agent**: [`ELASTIC_APM_API_KEY`](apm-agent-go://reference/configuration.md#config-api-key)
 * **.NET agent**: [`ApiKey`](apm-agent-dotnet://reference/config-reporter.md#config-api-key)
-* **iOS**: [`withApiKey`](opentelemetry://reference/edot-sdks/ios/configuration.md#withapikey)
+* **iOS**: [`withApiKey`](apm-agent-ios://reference/edot-ios/configuration.md#withapikey)
 * **Java agent**: [`api_key`](apm-agent-java://reference/config-reporter.md#config-api-key)
 * **Node.js agent**: [`apiKey`](apm-agent-nodejs://reference/configuration.md#api-key)
 * **PHP agent**: [`api_key`](apm-agent-php://reference/configuration-reference.md#config-api-key)

solutions/observability/apm/apm-agent-central-configuration.md

@@ -35,13 +35,13 @@ Each APM agent has a list of supported configurations. After selecting a Service
 Supported configurations are also tagged with the ![dynamic config](/solutions/images/observability-dynamic-config.svg "") badge in each APM agent’s configuration reference:
 
 Android agent
-:   [Configuration reference](opentelemetry://reference/edot-sdks/android/configuration.md)
+:   [Configuration reference](apm-agent-android://reference/edot-android/configuration.md)
 
 Go agent
 :   [Configuration reference](apm-agent-go://reference/configuration.md)
 
 iOS agent
-:   [Configuration reference](opentelemetry://reference/edot-sdks/ios/configuration.md)
+:   [Configuration reference](apm-agent-ios://reference/edot-ios/configuration.md)
 
 Java agent
 :   [Configuration reference](apm-agent-java://reference/configuration.md)

solutions/observability/apm/apm-server-binary.md

@@ -214,7 +214,7 @@ All that’s left is to compile and run your application. That’s it!
 
 **Learn more in the agent reference**
 
-Read more in the [APM Android Agent Reference](opentelemetry://reference/edot-sdks/android/index.md).
+Read more in the [APM Android Agent Reference](apm-agent-android://reference/edot-android/index.md).
 ::::::
 
 ::::::{tab-item} Go
@@ -340,7 +340,7 @@ var config = AgentConfigBuilder()
 
 **Learn more in the agent reference**
 
-Read more in the [APM iOS Agent Reference](opentelemetry://reference/edot-sdks/ios/index.md).
+Read more in the [APM iOS Agent Reference](apm-agent-ios://reference/edot-ios/index.md).
 ::::::
 
 ::::::{tab-item} Java

solutions/observability/apm/apm-server-fleet-managed.md

@@ -261,7 +261,7 @@ All that’s left is to compile and run your application. That’s it!
 
 **Learn more in the agent reference**
 
-Read more in the [APM Android Agent Reference](opentelemetry://reference/edot-sdks/android/index.md).
+Read more in the [APM Android Agent Reference](apm-agent-android://reference/edot-android/index.md).
 ::::::
 
 ::::::{tab-item} Go
@@ -387,7 +387,7 @@ var config = AgentConfigBuilder()
 
 **Learn more in the agent reference**
 
-Read more in the [APM iOS Agent Reference](opentelemetry://reference/edot-sdks/ios/index.md).
+Read more in the [APM iOS Agent Reference](apm-agent-ios://reference/edot-ios/index.md).
 ::::::
 
 ::::::{tab-item} Java

solutions/observability/apm/edot-sdks-central-configuration.md

@@ -34,12 +34,12 @@ Supported configurations are also tagged with the ![dynamic config](/solutions/i
 
 | Language/Platform | EDOT SDK | Configuration Reference |
 | --- | --- | --- |
-| Android | EDOT Android SDK | [Configuration reference](opentelemetry://reference/edot-sdks/android/configuration.md) |
-| iOS | EDOT iOS SDK | [Configuration reference](opentelemetry://reference/edot-sdks/ios/configuration.md) |
-| Java | EDOT Java SDK | [Configuration reference](opentelemetry://reference/edot-sdks/java/configuration.md) |
-| Node.js | EDOT Node.js SDK | [Configuration reference](opentelemetry://reference/edot-sdks/nodejs/configuration.md) |
-| PHP | EDOT PHP SDK | [Configuration reference](opentelemetry://reference/edot-sdks/php/configuration.md) |
-| Python | EDOT Python SDK | [Configuration reference](opentelemetry://reference/edot-sdks/python/configuration.md) |
+| Android | EDOT Android SDK | [Configuration reference](apm-agent-android://reference/edot-android/configuration.md) |
+| iOS | EDOT iOS SDK | [Configuration reference](apm-agent-ios://reference/edot-ios/configuration.md) |
+| Java | EDOT Java SDK | [Configuration reference](elastic-otel-java://reference/edot-java/configuration.md) |
+| Node.js | EDOT Node.js SDK | [Configuration reference](elastic-otel-node://reference/edot-node/configuration.md) |
+| PHP | EDOT PHP SDK | [Configuration reference](elastic-otel-php://reference/edot-php/configuration.md) |
+| Python | EDOT Python SDK | [Configuration reference](elastic-otel-python://reference/edot-python/configuration.md) |
 
 ## EDOT configuration [_edot_configuration]
 

solutions/observability/apm/secret-token.md

@@ -62,9 +62,9 @@ apm-server.auth.secret_token: <secret-token>
 
 Each Elastic {{apm-agent}} has a configuration option to set the value of the secret token:
 
-* **Android agent**: [`secretToken`](opentelemetry://reference/edot-sdks/android/configuration.md)
+* **Android agent**: [`secretToken`](apm-agent-android://reference/edot-android/configuration.md)
 * **Go agent**: [`ELASTIC_APM_SECRET_TOKEN`](apm-agent-go://reference/configuration.md#config-secret-token)
-* **iOS agent**: [`secretToken`](opentelemetry://reference/edot-sdks/ios/configuration.md#secrettoken)
+* **iOS agent**: [`secretToken`](apm-agent-ios://reference/edot-ios/configuration.md#secrettoken)
 * **Java agent**: [`secret_token`](apm-agent-java://reference/config-reporter.md#config-secret-token)
 * **.NET agent**: [`ELASTIC_APM_SECRET_TOKEN`](apm-agent-dotnet://reference/config-reporter.md#config-secret-token)
 * **Node.js agent**: [`Secret Token`](apm-agent-nodejs://reference/configuration.md#secret-token)

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

@@ -31,11 +31,11 @@ With an [Elastic Distribution of OpenTelemetry language SDK](opentelemetry://ref
 
 To set up OpenTelemetry with Elastic, refer to these guides for each language:
 
-* [**Elastic Distribution of OpenTelemetry Java**](opentelemetry://reference/edot-sdks/java/index.md)
-* [**Elastic Distribution of OpenTelemetry .NET**](opentelemetry://reference/edot-sdks/dotnet/index.md)
-* [**Elastic Distribution of OpenTelemetry Node.js**](opentelemetry://reference/edot-sdks/nodejs/index.md)
-* [**Elastic Distribution of OpenTelemetry Python**](opentelemetry://reference/edot-sdks/python/index.md)
-* [**Elastic Distribution of OpenTelemetry PHP**](opentelemetry://reference/edot-sdks/php/index.md)
+* [**Elastic Distribution of OpenTelemetry Java**](elastic-otel-java://reference/edot-java/index.md)
+* [**Elastic Distribution of OpenTelemetry .NET**](elastic-otel-dotnet://reference/edot-dotnet/index.md)
+* [**Elastic Distribution of OpenTelemetry Node.js**](elastic-otel-node://reference/edot-node/index.md)
+* [**Elastic Distribution of OpenTelemetry Python**](elastic-otel-python://reference/edot-python/index.md)
+* [**Elastic Distribution of OpenTelemetry PHP**](elastic-otel-php://reference/edot-php/index.md)
 
 ::::{important}
 For a complete overview of OpenTelemetry and Elastic, explore [**Elastic Distributions of OpenTelemetry**](opentelemetry://reference/index.md).

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](/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](/solutions/observability/get-started/opentelemetry/use-cases/llms/index.md) on how to setup and collect OpenTelemetry data for your LLM applications.
 
 ## Use cases