I had time to look at this during the flight, here it is:
----
index.html
typo: Diagnostic logs are critical in aiding in maintaining the
servicability -> critical in maintaining?
Overall, the first three sections, "What is Audit Logging", What is the
difference between audit logging and normal logging?" and "What is Log4j
Audit?" are very good: give good overview of the purpose and don't assume
prior knowledge.
>From the "Features" section, the narrative changes perspective from what
users would want to what Log4j Audit provides.
I would add a few sentences to that transition, something like:
{quote}
(after Features)
Each application has its own audit events. Before using Log4j Audit,
applications need to define AuditMessages that capture the exact attributes
of its audit events. The [Getting Started](link) page provides a tutorial
that explains how to define audit events for an application.
(after Audit Event Catalog header)
Once audit events are defined, they need to be maintained: as the
application evolves, developers will inevitably discover they need to add,
remove or change attributes of the audit events. Log4j Audit can persist
the audit event definitions in a JSON file. This file becomes the Audit
Event Catalog for the application. Log4j Audit is designed to store the
event definition file in a Git repository so that the evolution of the
audit events themselves have an audit trail in the Git history of the file.
Log4j Audit provides a web interface for editing the events.
Log4j Audit uses the catalog of events to determine ... (continue with
current text of Audit Event Catalog)
{quote}
Question about the Requirements section: it isn't clear to me (and likely
to other readers) why Dynamic Event Catalogs would require a database
instead of one or more JSON files. Is that explained somewhere? Perhaps
Dynamic Audit Events need a separate page or dedicated section somewhere.
The Getting Started page mentions "manage dynamic catalogs" in the
paragraph under "What you will build" but I couldn't find anything on the
topic of dynamic catalogs.
----
catalog.html
>From the first paragraph, I would remove "The events may be grouped by
Products and/or Categories, but at this time nothing in Log4j Audit makes
use of the product or catalog definitions". The same sentences is repeated
at the bottom of the page and since this feature is not used it is
confusing to me that the feature is so prominently mentioned in the first
paragraph of the page. I would consider removing this feature altogether.
Overall this is a very good page. Succinct but complete. Consider moving it
above RequestContext in the left-hand navigation menu.
----
gettingStarted.html
Overall, this page is only effective for people who actually perform the
steps and execute the commands mentioned in the page.
It would be good if the page would also be useful for people who only read
the page but don't actually perform the steps:
* Can the page also show an example of an audit event in JSON format. This
could be a simple event with few attributes (maybe a login event?) or the
transfer event that is used later in the page.
* I would also like to see the Java interface that is generated from this
JSON audit event.
* Finally, I would like to see how my application would use this generated
Java interface. How do I get an instance, how do I populate the attributes,
and what do I do with the instance after I populated it?
I'm sure the above is available in the source code of the sample
application, but this page is a good place to show some of the highlights
of that source code with some explanatory text.
Secondly, the page mentions remote audit logging and how the war file
provides endpoints for remove audit logging. Is it worth dedicating a
separate page to show how to configure end points for remote audit logging?
Finally, about the catalog screenshots: I understand that attributes are
managed separately so they can be reused. The second screenshot shows the
billPay and deposit events. Are these events related to the transfer event
that is mentioned in the curl example in this page? I was trying to see how
they could be related but couldn't figure it out.
Also, what are the attributes for the billPay and deposit events? If the
Catalog Editor has a screen to show the attributes that are part of an
event then it may be good to add a screenshot for this (I guess this would
be the Edit Event screen) as well. That would tie all these concepts
together.
----
requestContext.html
typo: typcial -> typical
typo: acrossall -> across all
typo: datbase -> database
About Mapping Annotations:
This is still a bit abstract to me. Would it be possible to provide some
more explanation on when applications should use ClientServer, when Local,
and when Chained annotations? Perhaps some example use cases? Or, if
possible, tie this to the use case presented in the sample application (if
that makes sense)?
About Transporting the RequestContext:
Until now, the information was generically useful for all applications, but
this section is specifically useful for web applications.
For people who don't work on web applications this transition may be a bit
jarring.
Would it make sense for this section and the following two sections to be
moved to a separate page? Something like "Web Applications" or "Remote
Audit Logging"?
----
Remko
On Mon, May 7, 2018 at 5:17 AM, Matt Sicker <boa...@gmail.com> wrote:
> I've been meaning to take a closer look at this. I'll review it over the
> next day or two.
>
> On 6 May 2018 at 16:26, Ralph Goers <ralph.go...@dslextreme.com> wrote:
>
> > I spoke too soon. I made a minor change to add a link to Apache events in
> > the site header.
> >
> > Ralph
> >
> > > On May 6, 2018, at 2:24 PM, Ralph Goers <ralph.go...@dslextreme.com>
> > wrote:
> > >
> > > I don’t think anything has changed since I last published but I will
> > rebuild it and publish it again.
> > >
> > > Ralph
> > >
> > >> On May 6, 2018, at 12:52 PM, Remko Popma <remko.po...@gmail.com>
> wrote:
> > >>
> > >> I’ll be flying back to Tokyo tomorrow but I can take another look when
> > I’m back. Is there a recent snapshot of the site on your GitHub account?
> > >>
> > >>
> > >>
> > >>> On May 6, 2018, at 21:35, Ralph Goers <ralph.go...@dslextreme.com>
> > wrote:
> > >>>
> > >>> I have finished everything I wanted to accomplish for the first
> > release of log4j-audit and so I am ready to generate a release candidate.
> > Before I do that I’d like to provide one more chance for feedback.
> > >>>
> > >>> Thoughts?
> > >>>
> > >>> Ralph
> > >>
> > >
> > >
> > >
> >
> >
> >
>
>
> --
> Matt Sicker <boa...@gmail.com>
>
