Skip to content

Commit

Permalink
docs: format/polish metric*, analysis*, config (#2960)
Browse files Browse the repository at this point in the history 
Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>
  • Loading branch information
@StackScribe @mowies
StackScribe and mowies committed Feb 6, 2024
1 parent e4ce3cc commit 293179f
Show file tree
Hide file tree
Showing 5 changed files with 184 additions and 196 deletions.
109 changes: 49 additions & 60 deletions docs/docs/reference/crd-reference/analysis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ that are used in the `AnalysisDefinition` query.
apiVersion: metrics.keptn.sh/v1beta1
kind: Analysis
metadata:
name: analysis-sample
name: <name-of-analysis>
spec:
timeframe: from: <start-time> to: <end-time> | `recent <timespan>`
args:
Expand All @@ -35,52 +35,55 @@ status:
```
## Fields
<!-- markdownlint-disable MD007 -->
* **apiVersion** -- API version being used
* **kind** -- Resource type.
Must be set to `Analysis`
* **metadata**
* **name** -- Unique name of this analysis.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.
* **name** -- Unique name of this analysis.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.
* **spec**
* **timeframe** (required) -- Specifies the range for the corresponding query
in the AnalysisValueTemplate.
This can be populated as one of the following:

* A combination of ‘from’ and ’to’
to specify the start and stop times for the analysis.
These fields follow the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt)
timestamp format.
* Set the ‘recent’ property to a time span.
This causes the Analysis to use data going back that amount of time.
For example, if `recent: 10m` is set,
the Analysis studies data from the last ten minutes.
If neither is set, the Analysis can not be added to the cluster.
* **args** -- Map of key/value pairs that can be used
to substitute variables in the `AnalysisValueTemplate` query.
* **analysisDefinition** (required) -- Identify the `AnalysisDefinition` resource
that stores the `AnalysisValuesTemplate` associated with this `Analysis`
* **name** -- Name of the `AnalysisDefinition` resource
* **namespace** (optional) --
Namespace of the `AnalysisDefinition` resource.
The `AnalysisDefinition` resource can be located in any namespace.
If the namespace is not specified,
the analysis controller looks for the `AnalysisDefinition` resource
in the same namespace as the `Analysis` resource.
* **status** -- results of this Analysis run,
added to the resource by Keptn,
based on criteria defined in the `AnalysisDefinition` resource.
<!-- markdownlint-disable -->
* **warning** -- Whether the analysis returned a warning.
* **raw** -- String-encoded JSON object that reports the results
of evaluating one or more objectives or metrics.
See
[Interpreting Analysis results](#interpreting-analysis-results)
for details.
* **state** -- Set to `Completed` or `Progressing` as appropriate.
* **timeframe** (required) -- Specifies the range for the corresponding query
in the AnalysisValueTemplate.
This can be populated as one of the following:

* A combination of ‘from’ and ’to’
to specify the start and stop times for the analysis.
These fields follow the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt)
timestamp format.
* Set the ‘recent’ property to a time span.
This causes the Analysis to use data going back that amount of time.
For example, if `recent: 10m` is set,
the Analysis studies data from the last ten minutes.

If neither is set, the Analysis can not be added to the cluster.

* **args** -- Map of key/value pairs that can be used
to substitute variables in the `AnalysisValueTemplate` query.
* **analysisDefinition** (required) -- Identify the `AnalysisDefinition` resource
that stores the `AnalysisValuesTemplate` associated with this `Analysis`
* **name** -- Name of the `AnalysisDefinition` resource
* **namespace** (optional) --
Namespace of the `AnalysisDefinition` resource.
The `AnalysisDefinition` resource can be located in any namespace.
If the namespace is not specified,
the analysis controller looks for the `AnalysisDefinition` resource
in the same namespace as the `Analysis` resource.
* **status** -- results of this Analysis run,
added to the resource by Keptn,
based on criteria defined in the `AnalysisDefinition` resource.
> **Warning** -- Whether the analysis returned a warning.
* **raw** -- String-encoded JSON object that reports the results
of evaluating one or more objectives or metrics.
See
[Interpreting Analysis results](#interpreting-analysis-results)
for details.
* **state** -- Set to `Completed` or `Progressing` as appropriate.
<!-- markdownlint-enable MD007 -->

## Interpreting Analysis results

Expand Down Expand Up @@ -260,6 +263,7 @@ based on the objectives evaluated (totalScore: 2).
<!-- markdownlint-disable-next-line -->
**`warning`** -- Indicates whether any warnings have been issued
during the evaluation (false in this case).
<!-- markdownlint-enable MD007 -->

## Usage

Expand Down Expand Up @@ -332,25 +336,10 @@ API reference: [Analysis](../api-reference/metrics/v1beta1/index.md#analysis)

## Differences between versions

Keptn v0.8.3 and v0.9.0 include a preliminary release
of the Keptn Analysis feature
but it is hidden behind a feature flag.
To preview these features, do one of the following for your Keptn cluster:

* Set the environment variable `ENABLE_ANALYSIS` to `true`
in the `metrics-operator` deployment
* Add the following to your `helm upgrade` command line:

```shell
--set metricsOperator.env.enableKeptnAnalysis=true
```
* Set `enableKeptnAnalysis: "true"` in the
[keptn-metrics-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/values.yaml)
file

See
[Customizing the configuration of components](../../installation/index.md#customizing-the-configuration-of-components)
for more information.
The Keptn Analysis feature is an official part of Keptn v0.10.0 and later.
Keptn v0.8.3 included a preliminary release of this feature
but it was hidden behind a feature flag.
The behavior of this feature is unchanged since v0.8.3.

## See also

Expand Down
160 changes: 82 additions & 78 deletions docs/docs/reference/crd-reference/analysisdefinition.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,84 +41,89 @@ spec:
```
## Fields
<!-- markdownlint-disable MD007 -->
* **apiVersion** -- API version being used
* **kind** -- Resource type.
Must be set to `AnalysisDefinition`.
* **metadata**
* **name** -- Unique name of this analysis definition.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.
* **namespace** -- Namespace where this resource is located.
`Analysis` resources must specify this namespace
when referencing this definition,
unless it resides in the same namespace as the `Analysis` resource.
* **metadata**
* **name** -- Unique name of this analysis definition.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.
* **namespace** -- Namespace where this resource is located.
`Analysis` resources must specify this namespace
when referencing this definition,
unless it resides in the same namespace as the `Analysis` resource.
* **spec**
* **objectives**
A list of objectives whose results are combined
to determine whether the analysis fails, passes, or passes with a warning.
* **analysisValueTemplateRef** (required) --
This string marks the beginning of each objective
* **name** (required) -- The `metadata.name` value of the
[AnalysisValueTemplateRef](analysisvaluetemplate.md)
resource that defines the SLI used for this objective.
That resource defines the data provider and the query to use.
* **namespace** --
Namespace of the `analysisValueTemplateRef` resource.
If the namespace is not specified,
the analysis controller looks for the `AnalysisValueTemplateRef` resource
in the same namespace as the `Analysis` resource.
* **target** -- defines failure or, optionally, warning criteria.
Values not specified for failure or warning result in a pass.
Keptn writes the results of the analysis to the `status` section
of the
[Analysis](analysis.md)
resource after the analysis runs.

To use a value that includes a fraction, use a Kubernetes
[quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/)
value rather than a `float`.
For example, use the `3m` quantity
rather than the `0.003` float;
a `float` value here causes `Invalid value` errors.
A whole number (integer) is also a legal `quantity` value.
* **failure** -- criteria for failure, specified as
`operator: <quantity>`.
This can be specified either as an absolute `quantity` value
or as a range of values.

Valid operators for absolute values are:
* `lessThan` -- `<` operator
* `lessThanOrEqual` -- `<=` operator
* `greaterThan` -- `>` operator
* `greaterThanOrEqual` -- `>=` operator
* `equalTo` -- `==` operator

Valid operators for specifying ranges are:
* `inRange` -- value is inclusively in the defined range
* `notInRange` -- value is exclusively out of the defined range

Each of these operators require two arguments:

* `lowBound` -- minimum `quantity` value
of the range included or excluded
* `highBound` -- maximum `quantity` value
of the range included or excluded
<!-- markdownlint-disable -->
* **warning** -- criteria for a warning,
specified in the same way as the `failure` field.
* **weight** -- used to emphasize the importance
of one `objective` over others
* **keyObjective** -- If set to `true`,
the entire analysis fails if this particular objective fails,
no matter what the actual `score` of the analysis is
* **totalScore** (required) --
* **passPercentage** -- threshold to reach for the full analysis
(all objectives) to pass
<!-- markdownlint-disable -->
* **warningPercentage** -- threshold to reach
for the full analysis (all objectives) to pass with `warning` status
* **objectives**
A list of objectives whose results are combined
to determine whether the analysis fails, passes, or passes with a warning.
* **analysisValueTemplateRef** (required) --
This string marks the beginning of each objective
* **name** (required) -- The `metadata.name` value of the
[AnalysisValueTemplateRef](analysisvaluetemplate.md)
resource that defines the SLI used for this objective.
That resource defines the data provider and the query to use.
* **namespace** --
Namespace of the `analysisValueTemplateRef` resource.
If the namespace is not specified,
the analysis controller looks for the `AnalysisValueTemplateRef` resource
in the same namespace as the `Analysis` resource.

* **target** -- defines failure or, optionally, warning criteria.
Values not specified for failure or warning result in a pass.
Keptn writes the results of the analysis to the `status` section
of the
[Analysis](analysis.md)
resource after the analysis runs.

To use a value that includes a fraction, use a Kubernetes
[quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/)
value rather than a `float`.
For example, use the `3m` quantity
rather than the `0.003` float;
a `float` value here causes `Invalid value` errors.
A whole number (integer) is also a legal `quantity` value.

* **failure** -- criteria for failure, specified as
`operator: <quantity>`.
This can be specified either as an absolute `quantity` value
or as a range of values.

Valid operators for absolute values are:

* `lessThan` -- `<` operator
* `lessThanOrEqual` -- `<=` operator
* `greaterThan` -- `>` operator
* `greaterThanOrEqual` -- `>=` operator
* `equalTo` -- `==` operator

Valid operators for specifying ranges are:

* `inRange` -- value is inclusively in the defined range
* `notInRange` -- value is exclusively out of the defined range

Each of these operators require two arguments:

* `lowBound` -- minimum `quantity` value
of the range included or excluded
* `highBound` -- maximum `quantity` value
of the range included or excluded
> **Warning** -- criteria for a warning,
specified in the same way as the `failure` field.

* **weight** -- used to emphasize the importance
of one `objective` over others
* **keyObjective** -- If set to `true`,
the entire analysis fails if this particular objective fails,
no matter what the actual `score` of the analysis is
* **totalScore** (required) --
* **passPercentage** -- threshold to reach for the full analysis
(all objectives) to pass
> **Warning** Percentage
for the full analysis (all objectives) to pass with `warning` status
<!-- markdownlint-enable MD007 -->

## Usage

Expand Down Expand Up @@ -150,11 +155,10 @@ API reference:

## Differences between versions

A preliminary release of the Keptn Analysis feature
is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag.
See the
[Analysis](analysis.md/#differences-between-versions)
reference page for instructions to activate the preview of this feature.
The Keptn Analysis feature is an official part of Keptn v0.10.0 and later.
Keptn v0.8.3 included a preliminary release of this feature
but it was hidden behind a feature flag.
The behavior of this feature is unchanged since v0.8.3.

## See also

Expand Down
Loading

0 comments on commit 293179f

Please sign in to comment.