fix: Log4j configurations and wording

[vy]

The current Log4j 2 documentation contains configurations with deprecated and redundant packages attributes, which cause runtime warnings for users – see apache/logging-log4j2#2966. This PR

• Removes the usage of the deprecated (and redundant) packages attribute
• Removes the usage of the redundant status attribute
• Adds XML namespace (to enable IDE assistance while users are editing)
• Adapt Log4j component and XML naming conventions
• Replaces occurrences of Log4j2 in text with Log4j 2

IS YOUR CHANGE URGENT?

Not urgent, can wait up to 1 week+

REVIEWERS

• @maciejwalkowiak
• @adinauer
• @ppkarwasz

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

@vy is attempting to deploy a commit to the Sentry Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
changelog	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 6, 2024 9:05am
develop-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 6, 2024 9:05am
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 6, 2024 9:05am

[lizokm]

@bitsandfoxes could you take a look at this when you have a moment?

[ppkarwasz]

@vy, looks great, but I would skip the schema location in the examples. Since Sentry is not in the generated XML Schema, the examples would not validate.

Some context for the Sentry team

We recently added a log4j-docgen tool that generates documentation and XML schemas from the Javadoc of elements annotated with @Plugin*.
You can find more information on the Log4j Docgen website.

A priori the tool could generate an XML Schema, which includes the Sentry element and all its options, but it is still pretty much rough around the edges and currently we only use it for our internal artifacts.

The long term plan, however, is:

• We ask Log4j Plugin vendors to publish a *-log4jdoc.xml artifact with each release.
• We configure Dependabot to watch for updates to sentry-log4j2.
• At each new release we regenerate our Plugin Reference to include Sentry,
• At each new release we regenerate our XSD Schemas to include a Sentry element.

As I mentioned before, right now such a process would be far from being easy, but in time it could show the size of the Log4j community and make logging.apache.org more of a common effort.

[vy]

@ppkarwasz, Thanks so much for the review.

I would skip the schema location in the examples. Since Sentry is not in the generated XML Schema, the examples would not validate.

I prefer to keep the schema location, since, contrary to the current situation (and your proposal) where there is no IDE assistance, my proposal will enable complete IDE assistance except for one line: <Sentry .../>. As can be seen from the user report in apache/logging-log4j2#2966, a typical Sentry user's log4j2.xml contains dozens of lines of code that can take advantage of the XML schema. All in all, I leave it at the discretion of the Sentry team whether to keep the XML schema location or not.

The long term plan, however, is:

Log4j team can ping Sentry again when this plan is realized.

[ppkarwasz]

I prefer to keep the schema location, since, contrary to the current situation (and your proposal) where there is no IDE assistance, my proposal will enable complete IDE assistance except for one line: <Sentry .../>. As can be seen from the user report in apache/logging-log4j2#2966, a typical Sentry user's log4j2.xml contains dozens of lines of code that can take advantage of the XML schema. All in all, I leave it at the discretion of the Sentry team whether to keep the XML schema location or not.

I think this is a problem that <xsd:include> could fix. A small XML schema could include the one at logging.apache.org add a Sentry type and override the org.apache.logging.log4j.core.Appender element group.

[lizokm]

@bitsandfoxes Hi! Could you take a look at this PR when you have a moment?

[bitsandfoxes]

@adinauer this looks like it's somewhere in your area of the world.

[lbloder]

Is there a particular reason for adding the level here, compared to the original?
Do you want to highlight the possibility of overriding the level like in docs/platforms/java/common/legacy/log4j2/index.mdx? If so, I would suggest to also add a comment here, like in the mentioned file.

[vy]

@lbloder, earlier the snippet was as follows:

<Root level="info">
  <AppenderRef ref="Sentry"/>
  <AppenderRef ref="Console"/>
</Root>

Though this didn't capture the configuration stated at the beginning of the java.log4j2.mdx file:

The following example using the log4j2.xml format to configure a ConsoleAppender that logs to standard out at the INFO level, and a SentryAppender that logs to the Sentry server at the ERROR level.

That is, sending ERRORs (and of higher severity) to Sentry was misconfigured – I fixed it.

Do you want to highlight the possibility of overriding the level like in docs/platforms/java/common/legacy/log4j2/index.mdx...

I am not able to follow you. I fixed legacy/log4j2/index.mdx too, since that document was stating:

The following example configures a ConsoleAppender that logs to standard out at the INFO level and a SentryAppender that logs to the Sentry server at the WARN level.

Hence, AFAIC, all configurations now match what is stated to be expected from them.

[lbloder]

@vy Sorry for the confusion.
Thank you, for fixing this, I just looked at the differences in the xml and thus overlooked the fact that the description was wrong in the first place.

I am not able to follow you. I fixed legacy/log4j2/index.mdx too, since that document was stating
I was referring to the inline comment above the AppenderRef that might be helpful for users copying the xml.
For example:

<Root level="info">
    <AppenderRef ref="CONSOLE"/>
		<!-- Note that the Sentry logging threshold is overridden to the ERROR level -->
    <AppenderRef ref="SENTRY" level="ERROR"/>
</Root>

[lbloder]

@vy @ppkarwasz I had a quick sync internally, and for now, we would like to keep the schema out of the examples due to the xml not being valid against the schema.

We will look into @ppkarwasz suggestion on creating our own schema that includes the Sentry element.

Also, whenever your long-term plan is realized, please let us know.

[vy]

@lbloder, how do you plan to proceed with this PR?

[lbloder]

@vy
Would you be so kind and apply the changes suggested by @ppkarwasz?

Then I think we can move foward and approve.

Thanks again for doing this 👍

[vy]

@vy Would you be so kind and apply the changes suggested by @ppkarwasz?

Done.

[lizokm]

@adinauer would you take a look when you have a moment please?

[getsantry]

This pull request has gone three weeks without activity. In another week, I will close it.

But! If you comment or otherwise update it, I will reset the clock, and if you add the label WIP, I will leave it alone unless WIP is removed ... forever!

---

"A weed is but an unloved flower." ― Ella Wheeler Wilcox 🥀

[vy]

@lbloder, @adinauer, would you mind reviewing this PR one last time, please? It is ready to be merged.

[adinauer]

Due to IntelliJ still complaining, we're removing the xmlns.

[lbloder]

@vy Thank your for bearing with us.
After testing with IntelliJ it would still mark the Sentry tag as not allowed, so we had to remove the xmlns attribute from the namespace. We will have to introduce this along with the schema once the [Log4j Docgen](https://logging.apache.org/log4j/tools/log4j-docgen.html) is ready.

We already pushed this change and approved the PR.

[vy]

@lbloder, @bitsandfoxes still appears as the last pending reviewer. Is there anything else I can do to get this PR merged?

[lbloder]

Sorry @vy, forgot to approve

[vy]

@lbloder, thanks for the prompt reaction. Yet AFAICS, your approval is not sufficient:

[adinauer]

Sorry for the delays and hickups, trying to figure out what's going on with CI so we can get this PR merged.