Doc updates: #370

jotak · 2023-06-09T08:02:41Z

Generalize using backticks for cross-references of spec fields, enum values, etc.
Format enum options as list when their description isn't too short
A few rephrasing (e.g. in conversation tracking)
should -> must

jotak · 2023-06-09T08:03:41Z

api/v1beta1/flowcollector_types.go

+	// logTypes defines the desired record types to generate. Possible values are:<br>
+	// - `FLOWS` (default) to export regular network flows<br>
+	// - `CONVERSATIONS` to generate events for started conversations, ended conversations as well as periodic "tick" updates<br>
+	// - `ENDED_CONVERSATIONS` to generate only ended conversations events<br>
+	// - `ALL` to generate both network flows and all conversations events<br>
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:Enum:="FLOWS";"CONVERSATIONS";"ENDED_CONVERSATIONS";"ALL"
 	// +kubebuilder:default:=FLOWS
 	LogTypes *string `json:"logTypes,omitempty"`

 	//+kubebuilder:default:="30s"
 	// +optional
-	// conversation heartbeat interval is the duration of time to wait between heartbeat reports of a conversation
+	// conversation heartbeat interval is the duration of time to wait between "tick" events of a conversation
 	ConversationHeartbeatInterval *metav1.Duration `json:"conversationHeartbeatInterval,omitempty"`

 	//+kubebuilder:default:="10s"
 	// +optional
-	// conversation end timeout is the duration of time to wait from the last flow log to end a conversation
+	// conversation end timeout is the time to wait after a network flow is received, to consider the conversation ended.
+	// This delay is ignored when a FIN packet is collected for TCP flows (see `conversationTerminatingTimeout` instead).
 	ConversationEndTimeout *metav1.Duration `json:"conversationEndTimeout,omitempty"`

 	//+kubebuilder:default:="5s"
 	// +optional
-	// conversation terminating timeout is the duration of time to wait from detected FIN flag to end a connection
+	// conversation terminating timeout is the time to wait from detected FIN flag to end a conversation. Only relevant for TCP flows.


@jpinsonneau can you review in particular this part? Is this all correct and makes sense?
I refer to "ticks" here since, if I'm right, this is how it is mentioned in the UI
Also added some precisions on the timeouts

Yes the frontend translate the events as:

switch (f.labels._RecordType) { case 'newConnection': return t('Conversation start'); case 'heartbeat': return t('Conversation tick'); case 'endConnection': return t('Conversation end'); case 'flowLog': default: return t('Flow'); }

jotak · 2023-06-09T08:07:35Z

@skrthomas I'll try also to fix something else in a next commit: our asciidoc generator doesn't handle very well the arrays kind of fields, e.g. "exporters" appears twice, first as "exporters | array" and then again as "exporters[] | object" - and only the description of the former is meant to be rendered. I'll see if I can fix that as a post-processing.

codecov · 2023-06-09T08:51:34Z

Codecov Report

Merging #370 (ec74312) into main (ad24dde) will decrease coverage by 0.05%.
The diff coverage is n/a.

❗ Current head ec74312 differs from pull request most recent head 31f8b5b. Consider uploading reports for the commit 31f8b5b to get more accurate results

@@            Coverage Diff             @@
##             main     #370      +/-   ##
==========================================
- Coverage   53.58%   53.54%   -0.05%     
==========================================
  Files          45       45              
  Lines        5488     5381     -107     
==========================================
- Hits         2941     2881      -60     
+ Misses       2337     2294      -43     
+ Partials      210      206       -4

Flag	Coverage Δ
unittests	`53.54% <ø> (-0.05%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
api/v1beta1/flowcollector_types.go	`100.00% <ø> (ø)`

... and 13 files with indirect coverage changes

skrthomas

I meant to publish these comments on Friday @jotak !! I finished reviewing and have a few things I noticed throughout. I've incorporated these new updates into the product doc.

docs/flowcollector-flows-netobserv-io-v1beta1.adoc

jotak · 2023-06-14T07:36:03Z

thanks @skrthomas , all comments addressed

skrthomas · 2023-06-14T20:43:52Z

@jotak I just got my peer review back and it seems like we have some more edits to make. Nothing big mostly just replacing may/might, some `` needed around parameters, commas, things like that.

jpinsonneau · 2023-06-16T08:00:05Z

api/v1beta1/flowcollector_types.go

-	// "IPFIX" works with OVN-Kubernetes CNI (other CNIs could work if they support exporting IPFIX,
+	// type selects the flows tracing agent. Possible values are:<br>
+	// - `EBPF` (default) to use NetObserv eBPF agent.<br>
+	// - `IPFIX` - <i>deprecated (*)</i> - to use the legacy IPFIX collector.<br>


is it deprecated or unsupported for 1.3+ ?

this one was ambiguous as it was deprecated before even our 1st GA ... but considering the history of the project upstream I would say it's deprecated, since it was once the only available option

jpinsonneau · 2023-06-16T08:07:10Z

api/v1beta1/flowcollector_types.go

+	// AuthToken describe the way to get a token to authenticate to Loki.<br>
+	// - `DISABLED` will not send any token with the request.<br>
+	// - `FORWARD` will forward the user token for authorization.<br>
+	// - `HOST` - <i>deprecated (*)</i> - will use the local pod service account to authenticate to Loki.<br>


same here: deprecated or unsupported for 1.3+ ?

Here I think it's clearly deprecated: it used to be a supported feature, and is not anymore

api/v1beta1/flowcollector_types.go

jotak · 2023-06-16T14:41:54Z

@skrthomas I applied the feedback from downstream, with the exception of the backticks on the field name being described (this one: openshift/openshift-docs#61006 (comment) ) : because it's a pattern we use almost everywhere in the file and not just at the place where it was suggested, if we want to do this change we should do it everywhere for consistency. So at the moment I haven't done the change ... but yes we could do it everywhere.

skrthomas · 2023-06-16T16:58:49Z

@jotak OK, I recopied your file. If it isn't too much trouble to regenerate with the backticks for the field name descriptions, lets go ahead and do that.

jotak · 2023-06-20T10:09:08Z

@skrthomas I'm not entirely sure yet how to proceed. We have 2 kinds of patterns:

With the field name being explicitly referenced and used as the subject of a verb like is or defines, e.g:

processor defines the settings of the component that receives the flows from the agent

In this case it seems legit to use the backticks: processor defines blah blah

More implicitly referencing the field name, e.g:

namespace where NetObserv pods are deployed

In this case it seems more "accidental" that the word is the same as the API field. This could be a problem for instance with this one:

Kafka configuration, allowing to use Kafka as a broker as part of the flow collection pipeline.

"Kafka" should take a capital K, unless it's referencing the field in which case perhaps we should reformulate using the 1. pattern:

`kafka` defines the configuration for Kafka, allowing to use it as a broker as part of the flow collection pipeline.

But it creates more repetitions so it's not pretty.

jotak · 2023-06-20T11:50:51Z

@skrthomas my last two commits include generalization of backticks, and reintroducing some lost rephrasing that were done only downstream (as shown in the current diff https://github.com/openshift/openshift-docs/pull/61006/files )

skrthomas · 2023-06-20T15:27:19Z

@skrthomas I'm not entirely sure yet how to proceed. We have 2 kinds of patterns:
1. With the field name being explicitly referenced and used as the subject of a verb like `is` or `defines`, e.g:
processor defines the settings of the component that receives the flows from the agent
In this case it seems legit to use the backticks: processor defines blah blah
2. More implicitly referencing the field name, e.g:
namespace where NetObserv pods are deployed
In this case it seems more "accidental" that the word is the same as the API field. This could be a problem for instance with this one:
Kafka configuration, allowing to use Kafka as a broker as part of the flow collection pipeline.
"Kafka" should take a capital K, unless it's referencing the field in which case perhaps we should reformulate using the 1. pattern:
`kafka` defines the configuration for Kafka, allowing to use it as a broker as part of the flow collection pipeline.
But it creates more repetitions so it's not pretty.

@jotak I think that the implicit references, like scenario 2, could be reformulated to be more like scenario 1. For example, it could be The namespace field specifies the namespace where the Network Observability pods are deployed.

For Kafka, Ah, ok thanks for clarifying the capitalization situational differences. And I agree, it can be reformulated also more like the 1 pattern.

skrthomas · 2023-06-22T15:09:35Z

/lgtm

skrthomas · 2023-06-16T17:03:45Z

docs/flowcollector-flows-netobserv-io-v1beta1.adoc

@@ -37,7 +37,7 @@ Type::
 | `object`
 | FlowCollectorSpec defines the desired state of FlowCollector.  +


Suggested change

| FlowCollectorSpec defines the desired state of FlowCollector. +

| spec defines the desired state of FlowCollector. +

Should this be just spec? 🤔

I've removed the mention of FlowCollectorSpec, but there must be other places with the same issue (that's not new btw, it was already like this previously)

- Generalize using backticks for cross-references of spec fields, enum values, etc. - Format enum options as list when their description isn't too short - A few rephrasing (e.g. in conversation tracking) - should -> must Remove some duplicate entries Apply suggestions from code review Co-authored-by: Sara Thomas <sarthoma@redhat.com> Regenerate doc Address downstream comments Update api/v1beta1/flowcollector_types.go Co-authored-by: Julien Pinsonneau <91894519+jpinsonneau@users.noreply.github.com> Generalize use of backticks Reintroduce some changes that were only downstream

openshift-ci · 2023-06-22T15:58:26Z

New changes are detected. LGTM label has been removed.

jotak · 2023-06-22T16:03:37Z

/approve

openshift-ci · 2023-06-22T16:03:43Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jotak

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [jotak]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

jotak requested a review from skrthomas June 9, 2023 08:02

jotak commented Jun 9, 2023

View reviewed changes

jotak requested review from memodi and jpinsonneau June 9, 2023 08:34

skrthomas reviewed Jun 12, 2023

View reviewed changes

skrthomas mentioned this pull request Jun 14, 2023

OSDOCS-6441: Updating FlowCollector API openshift/openshift-docs#61006

Merged

1 task

jpinsonneau reviewed Jun 16, 2023

View reviewed changes

api/v1beta1/flowcollector_types.go Outdated Show resolved Hide resolved

jpinsonneau previously approved these changes Jun 16, 2023

View reviewed changes

openshift-ci bot assigned jpinsonneau Jun 16, 2023

openshift-ci bot added the lgtm label Jun 16, 2023

jotak dismissed jpinsonneau’s stale review via 4a9a0a3 June 16, 2023 14:34

openshift-ci bot removed the lgtm label Jun 16, 2023

jotak force-pushed the doc-update branch from 4a9a0a3 to 57afe2c Compare June 16, 2023 14:37

openshift-ci bot assigned skrthomas Jun 22, 2023

openshift-ci bot added the lgtm label Jun 22, 2023

openshift-merge-robot added the needs-rebase label Jun 22, 2023

skrthomas approved these changes Jun 22, 2023

View reviewed changes

jotak force-pushed the doc-update branch from ec74312 to 31f8b5b Compare June 22, 2023 15:58

openshift-ci bot removed the lgtm label Jun 22, 2023

openshift-merge-robot removed the needs-rebase label Jun 22, 2023

openshift-ci bot added the approved label Jun 22, 2023

jotak merged commit 63c9a93 into netobserv:main Jun 22, 2023
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc updates: #370

Doc updates: #370

jotak commented Jun 9, 2023

jotak Jun 9, 2023 •

edited

Loading

jpinsonneau Jun 16, 2023

jotak commented Jun 9, 2023

codecov bot commented Jun 9, 2023 •

edited

Loading

skrthomas left a comment

jotak commented Jun 14, 2023

skrthomas commented Jun 14, 2023

jpinsonneau Jun 16, 2023

jotak Jun 16, 2023

jpinsonneau Jun 16, 2023

jotak Jun 16, 2023

jotak commented Jun 16, 2023

skrthomas commented Jun 16, 2023

jotak commented Jun 20, 2023

jotak commented Jun 20, 2023

skrthomas commented Jun 20, 2023 •

edited

Loading

skrthomas commented Jun 22, 2023

skrthomas Jun 16, 2023

skrthomas Jun 16, 2023

jotak Jun 22, 2023

openshift-ci bot commented Jun 22, 2023

jotak commented Jun 22, 2023

openshift-ci bot commented Jun 22, 2023

		@@ -37,7 +37,7 @@ Type::
		\| `object`
		\| FlowCollectorSpec defines the desired state of FlowCollector. +

	\| FlowCollectorSpec defines the desired state of FlowCollector. +
	\| spec defines the desired state of FlowCollector. +

Doc updates: #370

Doc updates: #370

Conversation

jotak commented Jun 9, 2023

jotak Jun 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jotak commented Jun 9, 2023

codecov bot commented Jun 9, 2023 • edited Loading

Codecov Report

skrthomas left a comment

Choose a reason for hiding this comment

jotak commented Jun 14, 2023

skrthomas commented Jun 14, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jotak commented Jun 16, 2023

skrthomas commented Jun 16, 2023

jotak commented Jun 20, 2023

jotak commented Jun 20, 2023

skrthomas commented Jun 20, 2023 • edited Loading

skrthomas commented Jun 22, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openshift-ci bot commented Jun 22, 2023

jotak commented Jun 22, 2023

openshift-ci bot commented Jun 22, 2023

jotak Jun 9, 2023 •

edited

Loading

codecov bot commented Jun 9, 2023 •

edited

Loading

skrthomas commented Jun 20, 2023 •

edited

Loading