(DOCSP-39541) Consolidate logging page #3273

krollins-mdb · 2024-05-23T16:09:59Z

Pull Request Info - SDK Docs Consolidation

Jira ticket: https://jira.mongodb.org/browse/DOCSP-39541

Staged Page

Logging

Page Source

Add links to every SDK's pages where you got the SDK-specific information:

Logging - C++ SDK
Logging - Flutter SDK
- Added new Logger examples because the current examples no longer work
Log Realm Events - Java SDK
Logging - Kotlin SDK
Logging - .NET SDK
Logging - Node.js SDK
Logging - Swift SDK
Log Realm Events - Java SDK
Set the Sync Client Log Level - C++ SDK
- All of the other SDKs' Sync Client Log Level page content will not be migrated. It's a deprecated feature that makes talking about logging awkward at best.

PR Author Checklist

Before requesting a review for your PR, please check these items:

Open the PR against the feature-consolidated-sdk-docs branch instead of master
Tag the consolidated page for:
- genre
- meta.keywords
- meta.description

Naming

Update Realm naming and the language around persistence layer/local/device per this document
Include .rst files comply with the naming guidelines

Links and Refs

Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections
Remove or update any SDK-specific refs to use the new consolidated SDK ref targets
Update any Kotlin API links to use the new Kotlin SDK roles

Content

Shared code boxes have snippets or placeholders for all 9 languages
API description sections have API details or a generic placeholder for all 9 languages
Check related pages for relevant content to include
Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic

Reviewer Checklist

As a reviewer, please check these items:

Shared code example boxes contain language-specific snippets or placeholders for every language
API reference details contain working API reference links or generic content
Realm naming/language has been updated
All relevant content from individual SDK pages is present on the consolidated page

github-actions · 2024-05-23T16:11:15Z

Readability for Commit Hash: d9296e5

You can see any previous Readability scores (if they exist) by looking
at the comment's history.

Readability scores for changed documents:

source/sdk/test-and-debug/log: Grade Level: 7.1, Reading Ease: 66.84

For Grade Level, aim for 8 or below.

For Reading Ease scores, aim for 60 or above:

Score	Difficulty
90-100	Very Easy
80-89	Easy
70-79	Fairly Easy
60-69	Medium
50-59	Fairly Hard
30-49	Hard
0-29	Very Hard

For help improving readability, try Hemingway App.

- re-consolidate set level content

- Minor edits

- Add sections for Java and C++ old sync loggers

- Remove Java and Objective C placeholders - Update wording for Java support

- Map Dart examples to new snippets

krollins-mdb · 2024-06-06T17:19:09Z

examples/dart/test/logger.dart

-      RealmInternal.logMessageForTesting(RealmLogLevel.trace,
-          "This message should be logged because the log level was changed");
+    // Hack to wait for stream to process
+    await delay(200);


This is a bit of a hack to wait for the stream to and listeners to do their thing.

I would love to make this code a more realistic use case and incorporate it into a Flutter app, but there's no time for that - especially as part of the consolidation project.

dacharyc

This is a great start! There are some things that come across kind of weird on on the consolidated page that I think we can improve, and there are some updates we should make to the metadata.

source/sdk/test-and-debug/log.txt

dacharyc · 2024-06-06T19:27:05Z

source/sdk/test-and-debug/log.txt

+
+.. include:: /includes/sdk-examples/logger/logging-turn-off-example.rst
+
+Java SDK: Deprecated Sync Logger


I think, instead of having two separate "Deprecated Sync Logger" sections for different SDKs, I'd probably rename this generically to:

"Deprecated Sync Logger"

And then use a tab group here to display the C++ and Java info.

For the tabs that aren't C++ or Java, I'd probably add a quick note saying something like:

The SDK deprecated the Sync logger in favor of the Realm logger in version . For versions and earlier, refer to the for details about the deprecated APIs.

I renamed the section to "Other Loggers" and have just two tabs: C++ and Java. I did this because, as you say, the Java logger isn't really the same thing as the deprecated Sync Logger. But the C++ SDK currently needs that Sync Logger. So, they're both different from the rest of the examples on the page.

dacharyc · 2024-06-06T19:31:00Z

source/sdk/test-and-debug/log.txt

+Java SDK: Deprecated Sync Logger
+--------------------------------
+
+The Java SDK's only logger is a deprecated sync logger that behaves differently


I'm not sure this is technically true? The RealmLogger in Java doesn't say anything about being restricted to a Sync logger - it's not in the Sync package, and the API reference docs say:

Global logger used by all Realm components. Custom loggers can be added by registering classes implementing RealmLogger.

So - I think this can be used similar to the other loggers, and it just doesn't have any examples other than setting the log level.

Yeah, I didn't frame this correctly. Thanks!

dacharyc · 2024-06-06T19:32:28Z

source/sdk/test-and-debug/log.txt

+
+.. _cpp-set-the-client-log-level:
+
+Set the Sync Client Log Level


We probably don't need a separate subheader here. It's taking more real estate/attention than I think it needs in the OtP. And if we make this a generic "Deprecated Sync Logger" header with tab groups for SDK-specific info, then I think we wouldn't want this header to show on the page anyway since it would only be in the C++ tab.

dacharyc · 2024-06-06T19:39:57Z

source/sdk/test-and-debug/log.txt

+
+.. include:: /includes/sdk-examples/logger/logging-set-custom-logger-example.rst
+
+After setting a custom logger, you may need to initialize the logger.


This reads a bit weird to me on languages where there is no example of initializing the logger. For example, on C#, there's a "missing example" placeholder below this copy. I wasn't sure if that's because the example is actually missing, or if you don't have to do a separate step of initializing the logger, since the copy here says "you may need to."

I think I would probably move this content for SDKs that require it up into the tab group above, and just omit it from here.

Then, I would include the "last" code example as the code example in the /includes/sdk-examples/logger/logging-set-custom-logger-example.rst file.

For example, for C++ - I see there's an example of initializing the logger below. I would make that the example in the /includes/sdk-examples/logger/logging-set-custom-logger-example.rst file, and then move the C++ example of actually defining the custom logger into the /includes/api-details/cpp/logger/logging-customize-logger-description.rst file.

Let me know if this makes sense or if you have Qs!

Hmm, yeah. I went back and forth trying to figure out how much structure to impose. Including initialization as an include in the SDK description hides the expected structure a bit (set -> initialize). But doing the way I currently am definitely makes it awkward for a couple of the SDKs.

dacharyc · 2024-06-06T19:45:20Z

temp/swift/app-services/connect-to-app-services-backend.txt

@@ -1,4 +1,3 @@
-.. _ios-init-appclient:


We should probably omit this file from the PR so we're not getting into merge conflicts in the temp directory.

Ah, right. I think I had a build error about ambiguous refs, so deleted this one. Before I realized the right way is to use the consolidated refs.

dacharyc · 2024-06-06T19:46:15Z

source/sdk/atlas/connect.txt

@@ -1,3 +1,4 @@
+.. _ios-init-appclient:


One of the units of work for this project is to remove SDK-specific ref targets, so we shouldn't add this here. We should just use the generic sdks-connect-to-atlas ref target if we need to link to this page.

Hmm. Yeah, I can't remember why I added it here. It's not used anywhere in the consolidated content. 🤷

Thanks for catching this!

source/includes/api-details/swift/logger/logging-set-change-level-description.rst

dacharyc · 2024-06-06T19:50:29Z

source/includes/api-details/kotlin/logger/logging-set-change-level-description.rst

+- MacOS logs to NSLog.
+- iOS logs to NSLog.
+
+.. include:: /includes/tip-sync-log-levels.rst


One of the benefits of consolidating the docs pages is that we generally shouldn't need generic includes, because we don't need to split content across a bunch of pages. Instead of nesting this includes here, I'd try taking the content out of the include and putting it directly on the main page wherever it needs to be.

Thanks for catching that. I do have this on the main page already. 😄

dacharyc

Just to avoid blocking this, changing my review status from "request changes" to "comment."

dacharyc

Trying again to change the review state to "comment" just so I don't block this while I'm out next week.

Co-authored-by: Dachary <[email protected]>

In particular, combine deprecated logger sections.

dacharyc

Looking good! Just a couple of things with tab IDs, and I think we need to add some generic placeholder content to the "Other Loggers" section for languages other than C++ or Java or else it looks like the page is missing text for that section.

dacharyc · 2024-06-17T21:12:26Z

source/sdk/test-and-debug/log.txt

+
+.. include:: /includes/sdk-examples/logger/logging-turn-off-example.rst
+
+Other Loggers


lol, I didn't think about this, but for languages other than C++ or C#, this section header now shows with no content. (i.e. Kotlin has an "Other Loggers" heading with no content.) I guess in this case, we should add something to the tabs. Maybe this would be a place to mention the deprecated Sync logger? i.e.

In SDK versions {FOO} and earlier, you could configure a Sync logger using methodName. That method has been deprecated in favor of the global logger.

One for each SDK with the version number in which the Sync logger was deprecated, and the Sync logger method name. I'd say we should avoid linking to the deprecated Sync logger API reference, because at some point those links will break. But it may be useful for folks using the older methods, if nothing else than to have the method name show up if they do a search in the docs so they can see it has been deprecated.

In addition to the comment below about Java content, this seems like a lot of effort and complexity for two minor, relatively unsupported, things. I think I'm going to go back to dedicated sections, but have them be under "Other Loggers".

source/sdk/test-and-debug/log.txt

source/includes/sdk-examples/logger/logging-set-change-level-example-2.rst

source/includes/sdk-examples/logger/logging-set-change-level-example.rst

source/includes/sdk-examples/logger/logging-set-custom-logger-example.rst

source/includes/sdk-examples/logger/logging-turn-off-example.rst

dacharyc · 2024-06-17T21:20:30Z

source/sdk/test-and-debug/log.txt

+   .. tab::
+      :tabid: csharp
+
+      The Java SDK uses an older Logger that may not behave like the other SDKs.


This content is in a csharp tab (maybe it was copied from above?), but it pertains to the Java SDK. We'll need to update this ID to java for this info, which means we'll have to add it to all of the tab sets on the page and the ones in the includes/sdk-examples/logger or we'll get Snooty errors about a missing tab. But since we don't have Java content that is relevant for those other sections, you'll have to use your judgement about what to put there. Maybe the missing API snippet for the code blocks, and I don't know if it's relevant to add text copy for each Java tab saying that the Java SDK uses a separate logger described below, or if we can just let the missing API snippet serve in those sections.

Co-authored-by: Dachary <[email protected]>

dacharyc

Nice work! I know this has been a big rethink about how the docs work versus the old way. I've got just a few more minor comments, but those are more subjective and not blockers. Thanks for all your effort on this!

dacharyc · 2024-06-25T13:23:19Z

source/sdk/test-and-debug/log.txt

+amounts of data depending on your development needs. You can specify 
+different log levels or custom loggers.
+
+.. warning:: Java SDK Logging Support


I don't love this bright red warning tab at the beginning of the page for an SDK we don't particularly want people to use. I think we should remove this warning block. It's not relevant if I'm here for any of the languages that we do support. There's a ToC entry in the OTP about Java SDK, so if I'm confused about why Java isn't in the language selector, I can just jump right to that section.

Makes sense to me! Should be a better experience without that warning.

dacharyc · 2024-06-25T13:24:57Z

source/sdk/test-and-debug/log.txt

+Java SDK
+~~~~~~~~
+
+The Java SDK uses an older Logger that may not behave like the other SDKs.


Just a general Q - should we be more specific about how this logger differs from the other SDKs?

Maybe. But I don't think it's worth spending more time on. I think I added this sentence to make it clear that the Java SDK wasn't using the same logger type as the other SDKs. But that's accomplished by putting it in the new "Other Loggers" section. I've removed this sentence as it doesn't add anything now and only invites questions. 😄

dacharyc · 2024-06-25T13:25:29Z

source/sdk/test-and-debug/log.txt

+The SDK logs events to the Android system log automatically. You can
+view these events using :android:`Logcat </studio/debug/am-logcat>`.
+
+To access newer logging features, use the Kotlin SDK.


And again, if we want to drive people to the Kotlin SDK, should we be more specific about what new features they'll get access to if they use the Kotlin SDK?

- reframe Java SDK content a bit

docs-builder-bot · 2024-06-25T19:04:39Z

✨ Staging URL: https://preview-mongodbmongodb.gatsbyjs.io/realm/feature-consolidated-sdk-docs/

🪵 Logs

job log: 569a50ddc067ea0c17b87d129562645bd95a28c1

krollins-mdb added 2 commits May 22, 2024 16:41

First pass

14f49ac

fix bad paths

8c9eb40

krollins-mdb added the merge to feature branch Unreleased feature - do not merge to Master label May 23, 2024

krollins-mdb changed the title ~~Docsp 39541~~ (DOCSP-39541) Consolidate logging page May 23, 2024

krollins-mdb added 20 commits May 24, 2024 10:27

Test combined customize content

e98a8aa

Small path fix and experiment

82811d1

More structure testing

e91b7ba

Test

63d0987

Restructure includes

7e78249

Clean up structure remnants

6f9809e

Couple more minor clean up things

e10cf3a

restructure includes again

127442a

final restructure?

d461571

Fix path refs

b74086a

Consolidate "turn off logging" section

12b2707

- rename an include set

0a83c05

- re-consolidate set level content

- Lots of file renaming

e8b4468

- Minor edits

- Add content only found in some SDK docs

7abc9d6

- Add sections for Java and C++ old sync loggers

Fix standalone Java examples

94e3cbe

- Move all example tab groups to includes

715e97c

- Remove Java and Objective C placeholders - Update wording for Java support

Upgrade deps

780eda2

Update Dart Logger test and generate snippets

ab1ccd2

- Rename example includes

701f54d

- Map Dart examples to new snippets

Minor edits

8622eeb

krollins-mdb marked this pull request as ready for review June 6, 2024 17:17

krollins-mdb commented Jun 6, 2024

View reviewed changes

dacharyc requested changes Jun 6, 2024

View reviewed changes

dacharyc reviewed Jun 6, 2024

View reviewed changes

dacharyc self-requested a review June 6, 2024 19:57

dacharyc reviewed Jun 6, 2024

View reviewed changes

krollins-mdb and others added 9 commits June 10, 2024 11:04

Apply suggestions from code review

f8a308c

Co-authored-by: Dachary <[email protected]>

Implement feeback.

a827d54

In particular, combine deprecated logger sections.

Implement feedback: combine tab groups

b18b8b9

Fix a couple issues

92eb6ef

Clean up

5403771

Fix other loggers tabs

6085112

Fix a link

80d3246

Adjust other loggers tab set

cc50829

Try to fix tab set again

3fc7eef

krollins-mdb requested a review from dacharyc June 17, 2024 18:21

dacharyc requested changes Jun 17, 2024

View reviewed changes

krollins-mdb and others added 3 commits June 24, 2024 19:36

Apply suggestions from code review

7ee8fab

Co-authored-by: Dachary <[email protected]>

Remove "other loggers" tab set

9db146d

Remove errant capital L

8385379

krollins-mdb requested a review from dacharyc June 25, 2024 00:49

dacharyc approved these changes Jun 25, 2024

View reviewed changes

- remove warning about Java SDK

d9296e5

- reframe Java SDK content a bit

krollins-mdb merged commit 569a50d into mongodb:feature-consolidated-sdk-docs Jun 25, 2024
7 checks passed

krollins-mdb deleted the DOCSP-39541 branch June 25, 2024 19:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(DOCSP-39541) Consolidate logging page #3273

(DOCSP-39541) Consolidate logging page #3273

krollins-mdb commented May 23, 2024 •

edited

Loading

github-actions bot commented May 23, 2024 •

edited

Loading

krollins-mdb Jun 6, 2024

dacharyc left a comment

dacharyc Jun 6, 2024

krollins-mdb Jun 10, 2024

dacharyc Jun 6, 2024

krollins-mdb Jun 10, 2024

dacharyc Jun 6, 2024

dacharyc Jun 6, 2024

krollins-mdb Jun 10, 2024

dacharyc Jun 6, 2024

krollins-mdb Jun 10, 2024

dacharyc Jun 6, 2024

krollins-mdb Jun 10, 2024

dacharyc Jun 6, 2024

krollins-mdb Jun 10, 2024

dacharyc left a comment

dacharyc left a comment

dacharyc left a comment

dacharyc Jun 17, 2024

krollins-mdb Jun 25, 2024 •

edited

Loading

dacharyc Jun 17, 2024

dacharyc left a comment

dacharyc Jun 25, 2024

krollins-mdb Jun 25, 2024

dacharyc Jun 25, 2024

krollins-mdb Jun 25, 2024

dacharyc Jun 25, 2024

docs-builder-bot commented Jun 25, 2024


		.. include:: /includes/sdk-examples/logger/logging-turn-off-example.rst

		Java SDK: Deprecated Sync Logger


		.. _cpp-set-the-client-log-level:

		Set the Sync Client Log Level


		.. include:: /includes/sdk-examples/logger/logging-set-custom-logger-example.rst

		After setting a custom logger, you may need to initialize the logger.


		.. include:: /includes/sdk-examples/logger/logging-turn-off-example.rst

		Other Loggers

(DOCSP-39541) Consolidate logging page #3273

(DOCSP-39541) Consolidate logging page #3273

Conversation

krollins-mdb commented May 23, 2024 • edited Loading

Pull Request Info - SDK Docs Consolidation

PR Author Checklist

Naming

Links and Refs

Content

Reviewer Checklist

github-actions bot commented May 23, 2024 • edited Loading

Choose a reason for hiding this comment

dacharyc left a comment

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

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dacharyc left a comment

Choose a reason for hiding this comment

dacharyc left a comment

Choose a reason for hiding this comment

dacharyc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krollins-mdb Jun 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dacharyc left a comment

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

docs-builder-bot commented Jun 25, 2024

🪵 Logs

krollins-mdb commented May 23, 2024 •

edited

Loading

github-actions bot commented May 23, 2024 •

edited

Loading

krollins-mdb Jun 25, 2024 •

edited

Loading