Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add metrics storage support to auto-generated CLI documentation #539

Merged
merged 4 commits into from
Dec 1, 2021
Merged

Add metrics storage support to auto-generated CLI documentation #539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d1b876e
Add metrics storage support to CLI auto generator
albertteoh Nov 30, 2021
74c1f85
Better error message and comments
albertteoh Nov 30, 2021
63c765e
Revert accidental update of 1.28
albertteoh Nov 30, 2021
95fdb94
Fix comment
albertteoh Nov 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions data/cli/next-release/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@
"badger",
"grpc-plugin"
],
"sampling": []
"sampling": [],
"metrics-storage": [
"prometheus"
]
},
"jaeger-collector": {
"storage": [
Expand All @@ -26,26 +29,32 @@
"sampling": [
"adaptive",
"file"
]
],
"metrics-storage": []
},
"jaeger-ingester": {
"storage": [
"cassandra",
"elasticsearch",
"grpc-plugin"
],
"sampling": []
"sampling": [],
"metrics-storage": []
},
"jaeger-query": {
"storage": [
"cassandra",
"elasticsearch",
"grpc-plugin"
],
"sampling": []
"sampling": [],
"metrics-storage": [
"prometheus"
]
},
"jaeger-agent": {
"storage": [],
"sampling": []
"sampling": [],
"metrics-storage": []
}
}
75 changes: 47 additions & 28 deletions scripts/gen-cli-data.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,48 @@
import json

if len(sys.argv) < 3:
print("You must supply a Jaeger version as the first argument and the output path as the second")
print("You must supply a Jaeger version as the first argument and "
"the output path as the second")
sys.exit(1)

jaeger_ver=sys.argv[1]
output_path=sys.argv[2]
jaeger_ver = sys.argv[1]
output_path = sys.argv[2]

with open("%s/data/cli/%s/config.json" % (output_path, jaeger_ver), 'r') as f:
cfg=json.load(f)
with open(f"{output_path}/data/cli/{jaeger_ver}/config.json", 'r') as f:
cfg = json.load(f)

def generate(tool, storage='', sampling=''):
print('Generating YAML for {}, storage {} and sampling {}'.format(tool, storage, sampling))

volume='%s/data/cli/%s:/data' % (output_path, jaeger_ver)
docker_img='all-in-one' if tool == 'jaeger-all-in-one' else tool
docker_image="jaegertracing/%s:%s" % (docker_img, jaeger_ver)
storageOrSampling=storage or sampling
# generate generates the CLI documentation for a given "tool" (e.g.
# jaeger-collector, jaeger-query, etc.) and feature (e.g. storage=elasticsearch,
# sampling=adaptive, metrics-storage=prometheus).
def generate(tool, **kwargs):
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think using kwargs would be simpler and cleaner than adding another "optional" parameter to support metrics storage, especially avoiding the need to extend the storageOrSampling variable.

if len(kwargs) > 1:
print(f"Expected at most 1 feature, got {len(kwargs)}.")
sys.exit(1)

feature_name = ""

# Get the first feature name (e.g. elasticsearch, adaptive, prometheus,
# etc.) in kwargs if it exists. The feature type (e.g. storage,
# sampling, metrics-storage) is not used, and hence ignored.
for _, feature_name in kwargs.items():
break

print(f'Generating YAML for tool: {tool}, feature: {feature_name}')

cmd=" ".join([
volume = f'{output_path}/data/cli/{jaeger_ver}:/data'
docker_img = 'all-in-one' if tool == 'jaeger-all-in-one' else tool
docker_image = f"jaegertracing/{docker_img}:{jaeger_ver}"

cmd = " ".join([
"docker run",
"--rm",
"--interactive",
"--privileged",
"--volume {}".format(volume),
"-e SPAN_STORAGE_TYPE={}".format(storage),
"-e SAMPLING_CONFIG_TYPE={}".format(sampling),
f"--volume {volume}",
f"-e SPAN_STORAGE_TYPE={kwargs.get('storage', '')}",
f"-e SAMPLING_CONFIG_TYPE={kwargs.get('sampling', '')}",
f"-e METRICS_STORAGE_TYPE={kwargs.get('metrics_storage', '')}",
docker_image,
"docs",
"--format=yaml",
Expand All @@ -36,24 +53,26 @@ def generate(tool, storage='', sampling=''):
print(cmd)
if os.system(cmd) != 0:
sys.exit(1)
if storageOrSampling:

if feature_name:
os.rename(
'{}/data/cli/{}/{}.yaml'.format(output_path, jaeger_ver, tool),
'{}/data/cli/{}/{}-{}.yaml'.format(output_path, jaeger_ver, tool, storageOrSampling)
)
f'{output_path}/data/cli/{jaeger_ver}/{tool}.yaml',
f'{output_path}/data/cli/{jaeger_ver}/{tool}-{feature_name}.yaml')


for tool in cfg['tools']:
tool_cfg = cfg[tool]
storage_types=tool_cfg['storage']
sampling_types=tool_cfg['sampling']
if storage_types:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These ifs were redundant as a "zero" value of a list just means the body of the for loop won't be executed.

for s in storage_types:
generate(tool=tool, storage=s)
if sampling_types:
for s in sampling_types:
generate(tool=tool, sampling=s)
storage_types = tool_cfg['storage']
sampling_types = tool_cfg['sampling']
metrics_storage_types = tool_cfg['metrics-storage']

for s in storage_types:
generate(tool=tool, storage=s)
for s in sampling_types:
generate(tool=tool, sampling=s)
for s in metrics_storage_types:
generate(tool=tool, metrics_storage=s)
generate(tool=tool)

print('Deleting _env/_docs/_version files')
os.system('bash -c "rm -rf data/cli/{}/*_*"'.format(jaeger_ver))
os.system(f'bash -c "rm -rf data/cli/{jaeger_ver}/*_*"')
38 changes: 34 additions & 4 deletions themes/jaeger-docs/layouts/shortcodes/cli/tools-list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
{{ $cli := index $data $tool }}
{{ $storage_types := index (index $config $tool) "storage" }}
{{ $sampling_types := index (index $config $tool) "sampling" }}
{{ $metrics_storage_types := index (index $config $tool) "metrics-storage" }}

<h2 id="{{ $tool }}">
{{ $tool }}
Expand Down Expand Up @@ -49,17 +50,32 @@ <h2 id="{{ $tool }}">
<p>{{ $tool }} can be used with these sampling types:</p>
<ul>
{{ range $sampling_types }}
{{ $storage := . }}
{{ $file := printf "%s-%s" $tool $storage }}
{{ $sampling := . }}
{{ $file := printf "%s-%s" $tool $sampling }}
<li>
<a href="#{{ $file }}">
{{ $tool }} with <code>{{ $storage }}</code>
{{ $tool }} with <code>{{ $sampling }}</code> sampling
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before: "... with adaptive"
After: "... with adaptive sampling"

</a>
</li>
{{ end }}
</ul>
{{ end }}

{{ if $metrics_storage_types }}
<p>(Experimental) {{ $tool }} can be used with these metrics storage types:</p>
<ul>
{{ range $metrics_storage_types }}
{{ $metrics_storage := . }}
{{ $file := printf "%s-%s" $tool $metrics_storage }}
<li>
<a href="#{{ $file }}">
{{ $tool }} with <code>{{ $metrics_storage }}</code> metrics storage
</a>
</li>
{{ end }}
</ul>
{{ end }}

{{ range $storage_types }}
{{ $storage := . }}
{{ $file := printf "%s-%s" $tool $storage }}
Expand All @@ -80,11 +96,25 @@ <h3 id="{{ $file }}">

<!-- TODO right sidebar gets too long, we should use tabs here -->
<h3 id="{{ $file }}">
{{ $tool }} with <code>{{ $sampling }}</code> sampling type
{{ $tool }} with <code>{{ $sampling }}</code> sampling
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before: "... with adaptive sampling type"
After: "... with adaptive sampling"

</h3>

{{ partial "options-table.html" $cli.options }}
{{ end }}

{{ range $metrics_storage_types }}
{{ $metrics_storage := . }}
{{ $file := printf "%s-%s" $tool $metrics_storage }}
{{ $cli := index $data $file }}

<!-- TODO right sidebar gets too long, we should use tabs here -->
<h3 id="{{ $file }}">
{{ $tool }} with <code>{{ $metrics_storage }}</code> metrics storage
</h3>

{{ partial "options-table.html" $cli.options }}
{{ end }}

{{ else }}
{{ partial "options-table.html" $cli.options }}
{{ end }}
Expand Down