Improvements to the Observability documentation

[Dilhasha]

Description

A. Suggestions for https://ballerina.io/learn/observe-ballerina-programs/

1. The below description can be structured better. suggestion: Ballerina achieves full observability by exposing itself to various external systems through three methods: monitoring metrics such as request count and response time statistics, performing distributed tracing, and analyzing logs.

2. Shall we add a table with what are the external tools we support for tracing, monitoring and logging?

3. In Step 2 under Observe a Ballerina service, We can mention that Ballerina.toml can be updated if we are using a Ballerina project and in this case, we are using a single bal file, so we need to use the flag.

B. Suggestions for https://ballerina.io/learn/observe-metrics/

1. The following description can be re-organized IMO, do we need to mention about analytics?

2. Configure advanced metrics - let's mention we need to add it to Config.toml file

3. Shall we mention that in this example we will use Prometheus for scraping the metrics and Grafana for visualization? Content gives the impression that we only support those.

4. docker run -p 19090:9090 -v <path_to_prometheus.yml>:/etc/prometheus/prometheus.yml prom/prometheus Resulted in an error as follows. source /var/lib/docker/overlay2/436e68d98a7d660cf0e49f44ac50936a44dd2a79e9cd0631a67495ed1e064235/merged/etc/prometheus/prometheus.yml is not directory

Modified to the following it worked. docker run -p 19090:9090 -v prometheus.yml:/etc/prometheus/ prom/prometheus

I noticed the same sample in the Prometheus documentation too using the path upto filename. Shall we check whether it's an edge case?

5. Do we need setting up the Grafana dashboard in this guide? IMO, that part is more suitable for a blog rather than the guide.

Steps to reproduce

The steps to be followed to reproduce the issue.

Affected version(s)

The versions that are affected by the issue.

Related website/documentation area

Add/Uncomment the relevant area label out of the following.

Related issue(s) (optional)

Any related issues such as sub tasks and issues reported in other repositories (e.g., component repositories), similar problems, etc.

Suggested label(s) (optional)

Optional comma-separated list of suggested labels. Non committers can’t assign labels to issues, and thereby, this will help issue creators who are not a committer to suggest possible labels.

Suggested assignee(s) (optional)

Optional comma-separated list of suggested team members who should attend the issue. Non committers can’t assign issues to assignees, and thereby, this will help issue creators who are not a committer to suggest possible assignees.

[Dilhasha]

B.4

This was due to an issue in the provided path. The path needs to be the isolated path. Even when you have the prometheus.yml in the current directory, it needs to be provided as ./prometheus.yml as follows.

docker run -p 19090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

The mapping should be from file to file OR directory to directory.

[anupama-pathirage]

@NipunaMadhushan Can we prioritize this to the update 9 related content plan?

[tharindu-nw]

Addressed these issues in https://github.com/ballerina-platform/ballerina-dev-website/pull/9535

Notes:

A 2. Shall we add a table with what are the external tools we support for tracing, monitoring and logging?

I had an offline chat with @keizer619 regarding this. The plan is to restructure the observability docs by adding separate pages for each tool we support. A summary of all the tools will be added then. Skipping this for now.

A 3. In Step 2 under Observe a Ballerina service, We can mention that Ballerina.toml can be updated if we are using a Ballerina project and in this case, we are using a single bal file, so we need to use the flag

This change was added in https://github.com/ballerina-platform/ballerina-dev-website/pull/9401

B 1. The following description can be re-organized IMO, do we need to mention about analytics?

This paragraph seems a bit disorganized and breaks the flow of the documentation. Decided to remove this as the points included does not expressly add value to the guide.

B 3. Shall we mention that in this example we will use Prometheus for scraping the metrics and Grafana for visualization? Content gives the impression that we only support those.

This will be fixed when the doc is moved to the prometheus specific page

B 4. Modified to the following it worked. docker run -p 19090:9090 -v prometheus.yml:/etc/prometheus/ prom/prometheus

Changed the docker run command to this. Felt that's better than including a note about isolated paths.

Also, changed outdated screenshots in the configuring grafana section.

[tharindu-nw]

Closing this as https://github.com/ballerina-platform/ballerina-dev-website/pull/9535 was merged

[github-actions[bot]]

This issue is NOT closed with a proper Reason/ label. Make sure to add proper reason label before closing. Please add or leave a comment with the proper reason label now.

      - Reason/EngineeringMistake - The issue occurred due to a mistake made in the past.
      - Reason/Regression - The issue has introduced a regression.
      - Reason/MultipleComponentInteraction - Issue occured due to interactions in multiple components.
      - Reason/Complex - Issue occurred due to complex scenario.
      - Reason/Invalid - Issue is invalid.
      - Reason/Other - None of the above cases.