Skip to content

Commit 1f593a9

Browse files
theletterfshainaraskascolleenmcginnisflorent-leborgneyetanothertw
authored
Add EDOT narrative docs (elastic#2942)
This PR contributes to elastic/opentelemetry-dev#1044 It brings the EDOT narrative documentation and adds an automation script to update a key variable. --------- Co-authored-by: shainaraskas <[email protected]> Co-authored-by: Colleen McGinnis <[email protected]> Co-authored-by: florent-leborgne <[email protected]> Co-authored-by: Vlada Chirmicci <[email protected]>
1 parent eac7a42 commit 1f593a9

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+2514
-69
lines changed
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Update Kube-Stack Version
2+
3+
on:
4+
schedule:
5+
# Run every Monday at 9:00 AM UTC
6+
- cron: '0 9 * * 1'
7+
workflow_dispatch: # Allow manual triggering
8+
9+
jobs:
10+
update-kube-stack-version:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
with:
17+
token: ${{ secrets.GITHUB_TOKEN }}
18+
19+
- name: Set up Python
20+
uses: actions/setup-python@v4
21+
with:
22+
python-version: '3.9'
23+
24+
- name: Run kube-stack version update script
25+
run: |
26+
cd scripts
27+
python update_kube_stack_version.py
28+
29+
- name: Check for changes
30+
id: verify-changed-files
31+
run: |
32+
if [ -n "$(git status --porcelain)" ]; then
33+
echo "changed=true" >> $GITHUB_OUTPUT
34+
else
35+
echo "changed=false" >> $GITHUB_OUTPUT
36+
fi
37+
38+
- name: Commit and push changes
39+
if: steps.verify-changed-files.outputs.changed == 'true'
40+
run: |
41+
git config --local user.email "[email protected]"
42+
git config --local user.name "GitHub Action"
43+
git add docs/docset.yml
44+
git commit -m "chore: update kube-stack version [skip ci]"
45+
git push
46+
47+
- name: Create Pull Request
48+
if: steps.verify-changed-files.outputs.changed == 'true'
49+
uses: peter-evans/create-pull-request@v5
50+
with:
51+
token: ${{ secrets.GITHUB_TOKEN }}
52+
commit-message: "chore: update kube-stack version"
53+
title: "chore: update kube-stack version"
54+
body: |
55+
This PR automatically updates the kube-stack version in `docs/docset.yml` based on the latest version from the elastic-agent repository.
56+
57+
**Changes:**
58+
- Updated kube-stack version in docset.yml
59+
60+
This PR was created automatically by the weekly kube-stack version update workflow.
61+
branch: update-kube-stack-version
62+
delete-branch: true
63+
labels: |
64+
automated
65+
documentation

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ This table compares Observability capabilities between {{ech}} deployments and O
111111
| **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 |
112112
| [**APM Agent Central Configuration**](/solutions/observability/apm/apm-agent-central-configuration.md) ||| Not available in Serverless |
113113
| [**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 |
114-
| [**Android agent/SDK instrumentation**](opentelemetry://reference/edot-sdks/android/index.md) ||| |
114+
| [**Android agent/SDK instrumentation**](apm-agent-android://reference/edot-android/index.md) ||| |
115115
| [**AWS Firehose integration**](/solutions/observability/cloud/monitor-amazon-web-services-aws-with-amazon-data-firehose.md) ||| |
116116
| [**Custom roles for Kibana Spaces**](/deploy-manage/manage-spaces.md#spaces-control-user-access) ||| |
117117
| [**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
121121
| **[Fleet Agent policies](/reference/fleet/agent-policy.md)** ||| |
122122
| **[Fleet server](/reference/fleet/fleet-server.md)** | - Self-hosted <br>- Hosted || Fully managed by Elastic |
123123
| [**Index lifecycle management**](/manage-data/lifecycle/index-lifecycle-management.md) ||| Use [**Data stream lifecycle**](/manage-data/lifecycle/data-stream.md) instead |
124-
| **[iOS agent/SDK instrumentation](opentelemetry://reference/edot-sdks/ios/index.md)** ||| |
124+
| **[iOS agent/SDK instrumentation](apm-agent-ios://reference/edot-ios/index.md)** ||| |
125125
| **[Kibana Alerts](/deploy-manage/monitor/monitoring-data/configure-stack-monitoring-alerts.md)** ||| |
126126
| **[LogsDB index mode](/manage-data/data-store/data-streams/logs-data-stream.md)** ||| - Reduces storage footprint <br> - Enabled by default <br>- Cannot be disabled |
127127
| **[Logs management](/solutions/observability/logs.md)** ||| |

docset.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,3 +294,4 @@ subs:
294294
ece-apis: https://www.elastic.co/docs/api/doc/cloud-enterprise/
295295
intake-apis: https://www.elastic.co/docs/api/doc/observability-serverless/
296296
models-app: "Trained Models"
297+
kube-stack-version: 0.6.3
Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
#!/usr/bin/env python3
2+
"""
3+
Kube-Stack Version Update Script
4+
5+
This script automatically updates the kube-stack version in the docset.yml file
6+
by fetching the latest version from the elastic-agent repository.
7+
8+
Usage:
9+
python update_kube_stack_version.py [--dry-run]
10+
11+
Options:
12+
--dry-run Show what would be updated without making changes
13+
"""
14+
15+
import urllib.request
16+
import re
17+
import sys
18+
import argparse
19+
from pathlib import Path
20+
21+
22+
def fetch_url_content(url):
23+
"""Fetch content from a URL"""
24+
try:
25+
print(f"Attempting to fetch: {url}")
26+
with urllib.request.urlopen(url) as response:
27+
content = response.read().decode('utf-8')
28+
return content
29+
except urllib.error.URLError as e:
30+
print(f"Failed to retrieve content: {e.reason}")
31+
return None
32+
33+
34+
def get_collector_version(file_path):
35+
"""Extract the collector version from docset.yml"""
36+
try:
37+
with open(file_path, 'r', encoding='utf-8') as file:
38+
content = file.read()
39+
40+
lines = content.splitlines()
41+
for line in lines:
42+
if line.strip().startswith('edot-collector-version:'):
43+
return line.split(':', 1)[1].strip()
44+
45+
# If no specific version is found, use a default version that we know works
46+
return '9.1.2'
47+
except FileNotFoundError:
48+
print(f"Error: Could not find {file_path}")
49+
return None
50+
except Exception as e:
51+
print(f"Error reading {file_path}: {e}")
52+
return None
53+
54+
55+
def get_kube_stack_version(version='main'):
56+
"""Extract KubeStackChartVersion from elastic-agent repository"""
57+
# Try different URL formats for the k8s.go file
58+
# First try with the version as-is (in case it already has 'v' prefix)
59+
url = f'https://raw.githubusercontent.com/elastic/elastic-agent/{version}/testing/integration/k8s/k8s.go'
60+
print(f"Trying k8s.go URL: {url}")
61+
content = fetch_url_content(url)
62+
63+
# If first attempt fails and version doesn't start with 'v', try with 'v' prefix
64+
if content is None and not version.startswith('v') and version != 'main':
65+
url = f'https://raw.githubusercontent.com/elastic/elastic-agent/v{version}/testing/integration/k8s/k8s.go'
66+
print(f"Retrying k8s.go with URL: {url}")
67+
content = fetch_url_content(url)
68+
69+
# If that fails too, try with main branch
70+
if content is None:
71+
url = 'https://raw.githubusercontent.com/elastic/elastic-agent/main/testing/integration/k8s/k8s.go'
72+
print(f"Falling back to main branch for k8s.go: {url}")
73+
content = fetch_url_content(url)
74+
75+
if content is None:
76+
print(f"Could not fetch k8s.go from any URL")
77+
return None
78+
79+
# Look for the KubeStackChartVersion line
80+
lines = content.splitlines()
81+
for line in lines:
82+
if 'KubeStackChartVersion' in line and '=' in line:
83+
# Extract the version from the line like: KubeStackChartVersion = "0.6.3"
84+
match = re.search(r'KubeStackChartVersion\s*=\s*"([^"]+)"', line)
85+
if match:
86+
return match.group(1)
87+
88+
print("Could not find KubeStackChartVersion in k8s.go")
89+
return None
90+
91+
92+
def update_docset_kube_stack_version(version, docset_path, dry_run=False):
93+
"""Update the kube-stack-version substitution in docset.yml"""
94+
try:
95+
with open(docset_path, 'r', encoding='utf-8') as file:
96+
content = file.read()
97+
98+
# Replace the kube-stack-version line
99+
pattern = r'(kube-stack-version:\s*)[0-9]+\.[0-9]+\.[0-9]+'
100+
replacement = f'\\g<1>{version}'
101+
new_content = re.sub(pattern, replacement, content)
102+
103+
if new_content != content:
104+
if dry_run:
105+
print(f"[DRY RUN] Would update kube-stack-version to {version} in {docset_path}")
106+
return True
107+
else:
108+
with open(docset_path, 'w', encoding='utf-8') as file:
109+
file.write(new_content)
110+
print(f"Updated kube-stack-version to {version} in {docset_path}")
111+
return True
112+
else:
113+
print(f"kube-stack-version already up to date: {version}")
114+
return False
115+
116+
except Exception as e:
117+
print(f"Error updating {docset_path}: {e}")
118+
return False
119+
120+
121+
def main():
122+
parser = argparse.ArgumentParser(description='Update kube-stack version in docset.yml')
123+
parser.add_argument('--dry-run', action='store_true',
124+
help='Show what would be updated without making changes')
125+
args = parser.parse_args()
126+
127+
# Get the script directory and construct paths relative to it
128+
script_dir = Path(__file__).parent
129+
docset_path = script_dir.parent / 'docset.yml'
130+
131+
print(f"Using docset.yml path: {docset_path}")
132+
133+
# Get the current collector version from docset.yml
134+
col_version = get_collector_version(docset_path)
135+
if col_version is None:
136+
print("Error: Could not determine collector version")
137+
sys.exit(1)
138+
139+
print(f"Collector version: {col_version}")
140+
141+
# Get the kube-stack version from elastic-agent repository
142+
kube_stack_version = get_kube_stack_version(col_version)
143+
if kube_stack_version is None:
144+
print("Error: Could not fetch kube-stack version")
145+
sys.exit(1)
146+
147+
print(f"Found kube-stack version: {kube_stack_version}")
148+
149+
# Update the docset.yml file
150+
success = update_docset_kube_stack_version(kube_stack_version, docset_path, args.dry_run)
151+
152+
if success:
153+
print("Kube-stack version update completed successfully")
154+
sys.exit(0)
155+
else:
156+
print("No update was needed or update failed")
157+
sys.exit(1)
158+
159+
160+
if __name__ == '__main__':
161+
main()

solutions/observability/apm/api-keys.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,10 +151,10 @@ To view all API keys for your project:
151151

152152
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:
153153

154-
* **Android**: [`apiKey`](opentelemetry://reference/edot-sdks/android/configuration.md)
154+
* **Android**: [`apiKey`](apm-agent-android://reference/edot-android/configuration.md)
155155
* **Go agent**: [`ELASTIC_APM_API_KEY`](apm-agent-go://reference/configuration.md#config-api-key)
156156
* **.NET agent**: [`ApiKey`](apm-agent-dotnet://reference/config-reporter.md#config-api-key)
157-
* **iOS**: [`withApiKey`](opentelemetry://reference/edot-sdks/ios/configuration.md#withapikey)
157+
* **iOS**: [`withApiKey`](apm-agent-ios://reference/edot-ios/configuration.md#withapikey)
158158
* **Java agent**: [`api_key`](apm-agent-java://reference/config-reporter.md#config-api-key)
159159
* **Node.js agent**: [`apiKey`](apm-agent-nodejs://reference/configuration.md#api-key)
160160
* **PHP agent**: [`api_key`](apm-agent-php://reference/configuration-reference.md#config-api-key)

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,13 @@ Each APM agent has a list of supported configurations. After selecting a Service
3535
Supported configurations are also tagged with the ![dynamic config](/solutions/images/observability-dynamic-config.svg "") badge in each APM agent’s configuration reference:
3636

3737
Android agent
38-
: [Configuration reference](opentelemetry://reference/edot-sdks/android/configuration.md)
38+
: [Configuration reference](apm-agent-android://reference/edot-android/configuration.md)
3939

4040
Go agent
4141
: [Configuration reference](apm-agent-go://reference/configuration.md)
4242

4343
iOS agent
44-
: [Configuration reference](opentelemetry://reference/edot-sdks/ios/configuration.md)
44+
: [Configuration reference](apm-agent-ios://reference/edot-ios/configuration.md)
4545

4646
Java agent
4747
: [Configuration reference](apm-agent-java://reference/configuration.md)

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ All that’s left is to compile and run your application. That’s it!
214214

215215
**Learn more in the agent reference**
216216

217-
Read more in the [APM Android Agent Reference](opentelemetry://reference/edot-sdks/android/index.md).
217+
Read more in the [APM Android Agent Reference](apm-agent-android://reference/edot-android/index.md).
218218
::::::
219219

220220
::::::{tab-item} Go
@@ -340,7 +340,7 @@ var config = AgentConfigBuilder()
340340

341341
**Learn more in the agent reference**
342342

343-
Read more in the [APM iOS Agent Reference](opentelemetry://reference/edot-sdks/ios/index.md).
343+
Read more in the [APM iOS Agent Reference](apm-agent-ios://reference/edot-ios/index.md).
344344
::::::
345345

346346
::::::{tab-item} Java

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ All that’s left is to compile and run your application. That’s it!
261261

262262
**Learn more in the agent reference**
263263

264-
Read more in the [APM Android Agent Reference](opentelemetry://reference/edot-sdks/android/index.md).
264+
Read more in the [APM Android Agent Reference](apm-agent-android://reference/edot-android/index.md).
265265
::::::
266266

267267
::::::{tab-item} Go
@@ -387,7 +387,7 @@ var config = AgentConfigBuilder()
387387

388388
**Learn more in the agent reference**
389389

390-
Read more in the [APM iOS Agent Reference](opentelemetry://reference/edot-sdks/ios/index.md).
390+
Read more in the [APM iOS Agent Reference](apm-agent-ios://reference/edot-ios/index.md).
391391
::::::
392392

393393
::::::{tab-item} Java

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,12 @@ Supported configurations are also tagged with the ![dynamic config](/solutions/i
3434

3535
| Language/Platform | EDOT SDK | Configuration Reference |
3636
| --- | --- | --- |
37-
| Android | EDOT Android SDK | [Configuration reference](opentelemetry://reference/edot-sdks/android/configuration.md) |
38-
| iOS | EDOT iOS SDK | [Configuration reference](opentelemetry://reference/edot-sdks/ios/configuration.md) |
39-
| Java | EDOT Java SDK | [Configuration reference](opentelemetry://reference/edot-sdks/java/configuration.md) |
40-
| Node.js | EDOT Node.js SDK | [Configuration reference](opentelemetry://reference/edot-sdks/nodejs/configuration.md) |
41-
| PHP | EDOT PHP SDK | [Configuration reference](opentelemetry://reference/edot-sdks/php/configuration.md) |
42-
| Python | EDOT Python SDK | [Configuration reference](opentelemetry://reference/edot-sdks/python/configuration.md) |
37+
| Android | EDOT Android SDK | [Configuration reference](apm-agent-android://reference/edot-android/configuration.md) |
38+
| iOS | EDOT iOS SDK | [Configuration reference](apm-agent-ios://reference/edot-ios/configuration.md) |
39+
| Java | EDOT Java SDK | [Configuration reference](elastic-otel-java://reference/edot-java/configuration.md) |
40+
| Node.js | EDOT Node.js SDK | [Configuration reference](elastic-otel-node://reference/edot-node/configuration.md) |
41+
| PHP | EDOT PHP SDK | [Configuration reference](elastic-otel-php://reference/edot-php/configuration.md) |
42+
| Python | EDOT Python SDK | [Configuration reference](elastic-otel-python://reference/edot-python/configuration.md) |
4343

4444
## EDOT configuration [_edot_configuration]
4545

solutions/observability/apm/secret-token.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,9 @@ apm-server.auth.secret_token: <secret-token>
6262
6363
Each Elastic {{apm-agent}} has a configuration option to set the value of the secret token:
6464
65-
* **Android agent**: [`secretToken`](opentelemetry://reference/edot-sdks/android/configuration.md)
65+
* **Android agent**: [`secretToken`](apm-agent-android://reference/edot-android/configuration.md)
6666
* **Go agent**: [`ELASTIC_APM_SECRET_TOKEN`](apm-agent-go://reference/configuration.md#config-secret-token)
67-
* **iOS agent**: [`secretToken`](opentelemetry://reference/edot-sdks/ios/configuration.md#secrettoken)
67+
* **iOS agent**: [`secretToken`](apm-agent-ios://reference/edot-ios/configuration.md#secrettoken)
6868
* **Java agent**: [`secret_token`](apm-agent-java://reference/config-reporter.md#config-secret-token)
6969
* **.NET agent**: [`ELASTIC_APM_SECRET_TOKEN`](apm-agent-dotnet://reference/config-reporter.md#config-secret-token)
7070
* **Node.js agent**: [`Secret Token`](apm-agent-nodejs://reference/configuration.md#secret-token)

0 commit comments

Comments
 (0)