Skip to content

Edit time series docs for clarity #3222

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
Open
wants to merge 24 commits into
base: main
Choose a base branch
from
Open

Edit time series docs for clarity #3222

wants to merge 24 commits into from

Conversation

marciw
Copy link
Contributor

@marciw marciw commented Sep 30, 2025 •
edited
Loading

Part of https://github.com/elastic/docs-team/issues/31?issue=elastic%7Cdocs-team%7C41

Status

🟢 Ready for PM/engineer review
🚧 Not ready for tech writer review

❗ Note for reviewers: We're going for "MVP" docs for now and tracking additional improvements in #3179

Changes

  • Revised overview: simplified, clarified
  • Revised setup: removed component templates, simplified
  • New advanced section (reindex, advanced concepts)

TODO:

  • Reconcile with recent changes to general data stream docs
  • Check docs patterns/style/etc.

@github-actions GitHub Actions
Copy link

github-actions bot commented Sep 30, 2025 •
edited
Loading

🔍 Preview links for changed docs

@kkrik-es kkrik-es requested a review from gmarouli September 30, 2025 13:27
@marciw marciw mentioned this pull request Sep 30, 2025
Closed
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
@kkrik-es kkrik-es requested a review from felixbarny October 1, 2025 06:54
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 1, 2025
View reviewed changes
@marciw marciw requested review from kkrik-es and gmarouli October 5, 2025 22:44
kkrik-es
kkrik-es reviewed Oct 6, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 6, 2025
View reviewed changes
kkrik-es
kkrik-es approved these changes Oct 6, 2025
View reviewed changes
Copy link
Contributor

@kkrik-es kkrik-es left a comment

Choose a reason for hiding this comment

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

Amazing, thanks!

gmarouli
gmarouli reviewed Oct 6, 2025
View reviewed changes
manage-data/data-store/data-streams/set-up-tsds.md
- To define a metric, use the `time_series_metric` mapping parameter. For more details, refer to [Metrics](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric).
- (Optional) Define a `date` or `date_nanos` mapping for the `@timestamp` field. If you don't specify a mapping, {{es}} maps `@timestamp` as a `date` field with default options.
* (Optional) Other index settings, such as [`index.number_of_replicas`](elasticsearch://reference/elasticsearch/index-settings/index-modules.md#dynamic-index-number-of-replicas), for the data stream's backing indices.
- A priority higher than `200`, to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.
Copy link
Contributor

@gmarouli gmarouli Oct 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I think we need to add here a lifecycle management section, at least for stateful, in serverless, this is enforced. I would recommend adding the following in the template:

"lifecycle": {
  "enabled": true
}

The main reason we need this is rollover, if a user doesn't add this they are going to end up with a gigantic index. Everything else is optional, we can leave it under the advanced set-up.

Copy link
Contributor

Choose a reason for hiding this comment

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

I second this - And I think that on the advanced setup we should at least explain why lifecycle management is useful for setting up rollover (quick one sentence to give them a reason on why the provided links are useful if they do not know about them)

gmarouli
gmarouli reviewed Oct 6, 2025
View reviewed changes
manage-data/data-store/data-streams/reindex-tsds.md
---

# Reindex a TSDS [tsds-reindex]
# Reindex a time series data stream [tsds-reindex]
Copy link
Contributor

Choose a reason for hiding this comment

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

@kkrik-es if I understand correctly, this reindexing manual is suggesting to reindex the data of one data stream into a single backing index of another data stream. Right?

If this is true, then I think we need to add a disclaimer before a user gets unpleasantly surprised.

We could also mention the reindex data stream API that was added for upgrades, I will check if it works.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah not ideal.. It's orthogonal to this PR tho, let's file an issue to provide a better path (I thought we had one..)

Copy link
Contributor

Choose a reason for hiding this comment

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

We should at least mention that the result will be a single index, like a note box or something, @marciw what do you think.

The rest is indeed orthogonal to this PR.

felixbarny
felixbarny reviewed Oct 6, 2025
View reviewed changes
kkrik-es
kkrik-es reviewed Oct 7, 2025
View reviewed changes
manage-data/data-store/data-streams/reindex-tsds.md
"routing_path": [ "metricset" ]
}
"index.mode": "time_series",
"index.routing_path": ["dimension_field"]
Copy link
Contributor

Choose a reason for hiding this comment

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

This setting gets auto-populated, let's remove it.

yannis-roussos
yannis-roussos reviewed Oct 7, 2025
View reviewed changes
Copy link
Contributor

@yannis-roussos yannis-roussos left a comment

Choose a reason for hiding this comment

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

Thank you Marci, looks great! I have added a few minor comments for your consideration.

Small additional thing I noticed: The link in the "Create a data stream and add sample data" section of the quickstart is now broken as we have moved the accepted time range section to the Time-bound indices page

manage-data/data-store/data-streams/set-up-tsds.md
- To define a metric, use the `time_series_metric` mapping parameter. For more details, refer to [Metrics](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric).
- (Optional) Define a `date` or `date_nanos` mapping for the `@timestamp` field. If you don't specify a mapping, {{es}} maps `@timestamp` as a `date` field with default options.
* (Optional) Other index settings, such as [`index.number_of_replicas`](elasticsearch://reference/elasticsearch/index-settings/index-modules.md#dynamic-index-number-of-replicas), for the data stream's backing indices.
- A priority higher than `200`, to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.
Copy link
Contributor

Choose a reason for hiding this comment

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

I second this - And I think that on the advanced setup we should at least explain why lifecycle management is useful for setting up rollover (quick one sentence to give them a reason on why the provided links are useful if they do not know about them)

marciw and others added 2 commits October 7, 2025 16:52
@marciw @yannis-roussos
Apply suggestion from review
cdfa095 
Co-authored-by: Yannis Roussos <[email protected]>
@marciw @yannis-roussos
Apply suggestion from review
a49050d 
Co-authored-by: Yannis Roussos <[email protected]>
@felixbarny @theletterf @kkrik-es
Add OTLP docs (#3360)
3fc8503 
Adds docs for the new OTLP endpoint added via
elastic/elasticsearch#133057

Closes #3363

---------

Co-authored-by: Fabrizio Ferri-Benedetti <[email protected]>
Co-authored-by: Kostas Krikellas <[email protected]>
@marciw @felixbarny
Apply suggestions from review
eeef3be 
Co-authored-by: Felix Barnsteiner <[email protected]>
@marciw @felixbarny
Apply suggestion from review
f42d458 
Co-authored-by: Felix Barnsteiner <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@felixbarny felixbarny felixbarny left review comments

@gmarouli gmarouli gmarouli left review comments

@kkrik-es kkrik-es kkrik-es approved these changes

@yannis-roussos yannis-roussos yannis-roussos approved these changes

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@marciw @felixbarny @gmarouli @kkrik-es @yannis-roussos