[SL-30] Updates to docs site #20

o11yguru · 2025-06-16T18:59:13Z

Updating docs site

Minor tweaks for readability.

textractor

I reviewed all of the files except the AWS ones.

textractor · 2025-06-17T03:21:07Z

content/quickstart/install.md

+    helm repo update
+    ```
+
+5. Install MDAI dependencies via Helm chart


I'm a little confused about this step. It doesn't give the command and is followed by a section on AWS and other stuff. Then we get step 6.

Not sure if you got an answer for this yet, but it is a little confusing.

The red box on the screenshot is the command. What is being said is you can set up with or without self observability or AWS however we recommend you do.

For the sake of the quick start, it may be good for us to put a note about if you do not set up AWS, you will see an error on the mdai-s3-log-reader, like it does on the 0.8 branch of the mdai-labs, but the the core of mdai will still work even with the error.

The manual install from 0.8 on mdai-labs may help as well.

textractor · 2025-06-17T03:33:11Z

content/quickstart/install.md

+
+6. Verify that the cluster's pods are running.
+    ```
+    kubectl get pods -n mdai


When I did this step, I got a couple of pods that couldn't be created:

mdai-s3-logs-reader-84b4659569-kvl7r 0/1 CreateContainerConfigError 0 28m
mdai-s3-logs-reader-9dc9c8764-dhzg2 0/1 CreateContainerConfigError 0

This is actually directly related to my comment above. Without setting up AWS credentials, you will receive this error, but everything should still work.

textractor · 2025-06-17T03:35:40Z

content/quickstart/install.md

+
+1. Apply the configuration to the hub resource.
+    ```
+    kubectl apply -f ./mdai/hub/0.8/hub_guaranteed_working.yaml -n mdai


There's a warning that I've not seen before: "Warning: ObserverResource observer-collector does not define a replica count" -- should we say something about ignoring that?

I would ignore this for now. I will try getting you some info on this.

textractor · 2025-06-17T03:49:53Z

content/quickstart/installMethods.md

+
+#### Install MDAI
+
+***Note**: Make sure you can access `values.yaml` your working directory. You have have to clone the `mdai-helm-chart` repo.*


remove double word "have have"

textractor · 2025-06-17T03:51:23Z

content/quickstart/installMethods.md

+
+>[!WARNING]
+>
+>Without this capability, you will not have access to our built-in, self-instrumentation that ensures visibility and accuracy of MDAI operations.


remove comma "...built-in self-instrumentation"

textractor · 2025-06-17T04:03:31Z

content/quickstart/collect.md

@@ -54,10 +53,10 @@ An OpenTelemetry collector is a component that receives and forwards telemetry d

 We'll use Fluentd to capture the synthetic log streams you created, and forward them to the collector.

-1. From the [MDAI Example Config repo](https://github.com/DecisiveAI/configs/blob/main/synthetics/loggen_fluent_config.yaml), copy the `loggen_fluent_config.yaml` into your working directory.
+1. Your working directory should still be pointed at [MDAI Labs repo](https://github.com/DecisiveAI/mdai-labs/). Run the following command:


Again remove the "working directory" advice. The fewer words, the lower the cognitive stress.

textractor · 2025-06-17T04:11:45Z

README.md

I tweaked the tweaks.

textractor · 2025-06-17T04:42:39Z

content/quickstart/self_monitoring.md

+
+## About Self-monitoring
+
+The MDAI Smart Telemetry Hub contains complex infrastructure. To maintain and monitor operational excellence, we have included an opt-in capability to create an understanding internal metrics, audit history of change events, and log streams affording traceability across our services and their events.


"create an understanding of internal metrics" ?

textractor · 2025-06-17T04:44:51Z

content/quickstart/self_monitoring.md

+
+The `mdai-helm-chart` installed `mdai-operator` and `mdai-gateway` expect a destination to send their logs to, but this chart does not manage deploying the logs destination for those services.
+
+The `mdai-operator` has the ability to manage an opinionated collector, via compatible configurations, called the `mdai-collector` (sometimes referred to as the `hub-monitor`). The `mdai-collector` receives from this fixed list of services and sends the logs to a compatible destination.


Did we mention what "this fixed list of services" is?

textractor · 2025-06-17T04:48:17Z

content/quickstart/self_monitoring.md

I'm a little concerned about users being able to understand what this means for them in a quick start. I mentioned in another comment that this seems to be adding complexity a little early, without enough context.

fix a few broken links

textractor · 2025-06-18T03:42:21Z

content/quickstart/filter.md

@@ -33,14 +33,13 @@ But not all logs are created equal. Now that we're generating log data, let's fi

 MDAI is monitoring services by a service identifier (log attribute), `mdai_service`, and a tolerance threshold over a rolling time window. When a given service surpasses that threshold, we'd like to drop non-critical data such as log lines with a level below WARN.

-To do that, let's add a managed filter to `otel_config.yaml`, the collector's configuration file. Open the file for editing and look for the configuration block that looks like this:
+To do that, let's add a managed filter to `otel/0.8/otel_guaranteed_working.yaml`, the collector's configuration file. Open the file for editing and look for the configuration block that looks like this:

 ```
    # filter/service_list:


In the otel/0.8/otel_guaranteed_working.yaml I'm pulling from mdai_labs right now all of that is already uncommented. So is the next line below that's supposed to be commented out. So that file needs to be updated as well?

And so when I apply this config, nothing seems to change?

> kubectl apply -f otel/0.8/otel_guaranteed_working.yaml --namespace mdai opentelemetrycollector.opentelemetry.io/gateway unchanged

So I'm not sure the filter is actually doing anything. We used to have a filter that specified filtering out INFO level logs.

textractor · 2025-06-18T03:55:09Z

content/quickstart/aws/setup_iam_longterm_user_s3.md

+>
+> 🛑 **Warning**
+>
+> We do not recommend using this setup for a development or greater environment -- this is truly for the quickstart. If you're in AW EKS, we recommend [IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) for a similar effect.


"If you're in AW EKS ..." → "AWS"?

textractor · 2025-06-18T03:56:23Z

content/quickstart/aws/setup_iam_longterm_user_s3.md

+
+##### Create / Use `.env` file to store Access Keys
+
+If you don't already, create a `.env` file. Then, update the `.env` file to have your credentials. It should look similar to the following:


"don't" → "haven't"

textractor · 2025-06-18T04:03:44Z

content/quickstart/aws/setup_iam_longterm_user_s3.md

+
+>[!NOTE]
+>
+>To stop logs from sending to s3, you will need to delete the MdaiCollector Custom Resource


"the MdaiCollector Custom Resource" → "the MDAI Collector Custom Resource (CR)"

Looks like it's called "MDAI Collector" below; also below we start using "CR" so would be nice to show that.

shalane-proctor · 2025-06-25T02:46:06Z

@textractor Was trying to go through each of your comments on this PR, but maybe it would be better we work together on it some time this week because I'm a bit confused now and seemingly a lot has happened since your first comment. Sent you a DM, but adding here for visibility.

Trent Vigar and others added 3 commits June 16, 2025 09:08

Updating readme, fixing typos, and updates for v0.8 release

7721da1

docs: update docs to reflect 0.8

2d25fe2

[SL-30] docs: contnet updates galore

951c1e0

o11yguru force-pushed the v0.8 branch 3 times, most recently from 04237d0 to a098274 Compare June 16, 2025 20:58

o11yguru marked this pull request as ready for review June 16, 2025 22:02

[SL-30] docs: contnet updates galore

795e3e7

o11yguru force-pushed the v0.8 branch from a098274 to 795e3e7 Compare June 16, 2025 22:23

Robin-Law and others added 2 commits June 16, 2025 17:49

fix a few broken links

28bcbac

Update README.md

1ed56be

Minor tweaks for readability.

textractor requested changes Jun 17, 2025

View reviewed changes

Trent Vigar and others added 2 commits June 17, 2025 13:59

Updating filter page with updated 0.8 labs files

37a291b

Merge pull request #24 from DecisiveAI/rlaw/0.8.0-fixes

2b974c4

fix a few broken links

textractor requested changes Jun 18, 2025

View reviewed changes


		#### Install MDAI

		*Note: Make sure you can access `values.yaml` your working directory. You have have to clone the `mdai-helm-chart` repo.*


		## About Self-monitoring

		The MDAI Smart Telemetry Hub contains complex infrastructure. To maintain and monitor operational excellence, we have included an opt-in capability to create an understanding internal metrics, audit history of change events, and log streams affording traceability across our services and their events.


		The `mdai-helm-chart` installed `mdai-operator` and `mdai-gateway` expect a destination to send their logs to, but this chart does not manage deploying the logs destination for those services.

		The `mdai-operator` has the ability to manage an opinionated collector, via compatible configurations, called the `mdai-collector` (sometimes referred to as the `hub-monitor`). The `mdai-collector` receives from this fixed list of services and sends the logs to a compatible destination.


		##### Create / Use `.env` file to store Access Keys

		If you don't already, create a `.env` file. Then, update the `.env` file to have your credentials. It should look similar to the following:

[SL-30] Updates to docs site #20

Are you sure you want to change the base?

[SL-30] Updates to docs site #20

Uh oh!

Conversation

o11yguru commented Jun 16, 2025

Uh oh!

textractor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shalane-proctor commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

shalane-proctor commented Jun 25, 2025 •

edited

Loading