Ralph,

very nice improvements! Especially the first page does a great job at
explaining what audit logging is and why/when you would want to use it.

The Getting Started page then does a tutorial-style deep dive into using
Log4j Audit, but unfortunately gets a bit bogged down in setting up the
toolchain, and seems to stop half-way through.

Would it be possible to show a diagram that visually explains the usage
workflow at a glance? For example, for diagnostic logging with Log4j2, a
common workflow is:
Step 1 (Configuration): using a text editor, create a configuration file.
Step 2 (Installation): put the configuration file and the Log4j jars in
your classpath
Step 3 (API setup): call `LogManager.getLogger()` to obtain a Logger. It is
convenient to store a reference to this logger in a private static field.
Step 4: use the API to log stuff

With Audit Logging, the workflow is more involved. Part of that is the tool
chain, but it seems to me that there are simply more steps before users can
get to the “log stuff“ part. A diagram that allows users to grasp this
workflow at a glance would be great. It would be good if users can get an
overview-level understanding without needing to do the deep dive tutorial.

So, what is the Audit Logging workflow? I'm guessing (correct me if I'm
wrong) something like this:

Step 1 (Analysis): find places in your application where state
modifications occur that you want to keep a track record for
Step 2 (Install the toolchain): this is covered on the Getting Started page
Step 3 (Design): use the toolchain to create Audit Events for the state
modifications discovered in Step 1. Attributes of these Audit Events are
put in an attribute pool and can be shared by other events, so it's
important to give them good names. Audit Event attributes must also have a
data type. Description etc are optional. (From the Audit Catalog page I get
the impression that attributes must be created first and can only later be
combined into Audit Events. It may be more natural for users to start with
an Audit Event and then either pick an existing attribute or create new
attributes while building up this Audit Events definition. Such attributes
can still be put in the shared pool.)
*(from here on I'm just guessing...)*
Step 4 (Code Generation): when you're happy with the Audit Event
definition, use the toolchain to generate Java interfaces for the Audit
Events. This results in a JAR that you can add to the classpath of your
application.
Step 5: log stuff. In your application, you can use XXX (factory?,
constructor?) to instantiate an instance of the generated interface. This
interface extends AuditMessage and has setters and getters (or does it use
a builder?) for the attributes of the AuditEvent. At places in the
application where a state modification occurs that you want to keep a track
record for, populate the attributes  for the appropriate AuditMessage and
log it. (Question: Should users configure a separate logger for
AuditMessages or can the diagnostic logger be used and are the
AuditMessages separated downstream with filters etc? What is the
recommended setup for this?)

The Getting Started page covers Step 2, and the Audit Catalog page explains
Step 3, but I could not find anything for Step 4 and 5. It would be good to
explain this workflow from a user's point of view, rather than from a tool
provider's point of view.

About the toolchain, the Getting Started page mentions that there is a WAR
file, and then asks users to install a servlet container. However, the
recommended setup is for users to run this container locally. Why not
provide this as a standalone application with an embedded servlet
container? The underlying WAR could always be deployed elsewhere but this
would give a nicer user experience out of the box.

Some additional questions:
* Git is part of the toolchain but I'm not clear what its purpose is. The
catalog can be exported from the in-memory database in JSON format (and
imported again I assume), so is git just to version and distribute the
persisted catalog? Would another version control system also work? Would
just plain file system also work?
* Are the generated interfaces stored somewhere? Also in git? Are they
versioned also?

About RequestContext:
I still think this page jumps in too deep too fast and I can't follow...
I gather that the use of this class is optional.
Users could use the generated interfaces to log AuditMessages directly, no?
To me, logging AuditMessages via custom (auto-generated) interfaces seems
easiest to understand.
Is it fair to say that RequestContext  is only useful in web applications,
and particularly in Spring-based web applications? It may be good to
mention that explicitly in the beginning.

You mention that RequestContext is useful to
(1) capture common elements, so the custom Audit Events can be smaller and
become easier to use, and
(2) provide a thread-safe way to pass data between several layers.

Those features seem generally useful (also outside of web apps). In
addition to these two, I gather that RequestContext provides functionality
that makes it easy to integrate with the Spring services. I assume that
this is where the annotations come into play. I don't have enough Spring
expertise to understand the explanation for the annotations. It is unclear
to me whether these annotations would be useful (or generally how
RequestContext could be used) outside the Spring world, or even outside of
web applications.

I like the diagram under Transporting the RequestContext though. Diagrams
are good! I like diagrams!

It may be good to have another page showing very basic Audit logging with
the generated interfaces, without RequestContext (perhaps for a non-web
app).

I'll stop here. Let me know what you think.
Remko


On Mon, Feb 12, 2018 at 11:01 Remko Popma <remko.po...@gmail.com> wrote:

> Ok, I’ll try tonight if I can.
>
>
>
> > On Feb 12, 2018, at 9:31, Ralph Goers <ralph.go...@dslextreme.com>
> wrote:
> >
> > Remko,
> >
> > I believe I have addressed most of the feedback from these two emails,
> although I haven’t figured out how the selected component stays highlighted
> in the left hand menu. I’d appreciate you and everyone else taking another
> look at https://rgoers.github.io/log4j-audit/index.html <
> https://rgoers.github.io/log4j-audit/index.html>.
> >
> > Thanks,
> > Ralph
> >
> >> On Feb 5, 2018, at 8:04 AM, Remko Popma <remko.po...@gmail.com> wrote:
> >>
> >> About the web site, the project seems to have components, but the
> component
> >> links in the left-hand navigation menu are not very useful:
> >> If you click on "Audit API" for example, only some standard
> Maven-generated
> >> component links/pages are visible, no javadoc or sources in the
> Component
> >> Reports.
> >> Also the selected component should stay highlighted in the left-hand
> menu
> >> like we do for the Log4j 2 web site.
> >>
> >> The Javadoc page at the top of the left-hand navigation menu seems
> broken:
> >> it shows the Log4j 2 modules, not the log4j-audit modules.
> >> The submenu links under Javadoc (e.g. Javadoc/Log4j Audit API) all give
> 404
> >> page not found errors.
> >>
> >>
> >>
> >>> On Mon, Feb 5, 2018 at 11:49 PM, Remko Popma <remko.po...@gmail.com>
> wrote:
> >>>
> >>> Some first impression feedback:
> >>>
> >>> Top page:
> >>> I think it is worth explaining the motivation/use case for audit
> logging
> >>> here. What is "audit logging"? How is audit logging different from
> "normal"
> >>> logging? What kind of applications would want to use audit logging and
> why?
> >>> What are audit events? How do audit events relate to log events?
> >>>
> >>> RequestContext page:
> >>> I had trouble following this page. The explanation is going too fast
> for
> >>> me and seems to be skipping over some steps. Is my understanding below
> >>> correct?
> >>> * Users must create a RequestContext to use audit logging (if true,
> best
> >>> to start by saying that)
> >>> * The reason users need to create a RequestContext is to have a single
> >>> container for all data points that users want to log in their audit
> log.
> >>> (Question: does this mean that RequestContext = Audit Event?)
> >>> * A recommended/convenient way to implement a RequestContext is to
> stuff
> >>> all values in the log4j ThreadContext (Question: is it really okay to
> >>> assume that the service container does not hand off requests to worker
> >>> threads?)
> >>> * The example RequestContext implementation is too long (and
> repetitive -
> >>> readers will get the point after a few attributes) - may be better to
> place
> >>> the full class in an example application and only show snippets in this
> >>> page (and perhaps link to the full example from the page)
> >>> * After the example follows some explanation about the annotations.
> Seems
> >>> pretty important stuff but is now just a wall of text. I would break
> it up
> >>> into sections with bold headers, a separate section for each
> annotation.
> >>> Current explanation of the annotations seems a bit too brief.
> >>> *  RequestContextInterceptor example seems a bit long. Can you reduce
> it
> >>> to its essence or break it up? (Also formatting seems off and has
> missing
> >>> closing double quote in response.sendRedirect("/login); , but does
> this
> >>> page really need to contain a fully working example?)
> >>> * Finally, the the "passing context to service" section: are
> >>> RequestContextInterceptor and  RequestContextHeaderInterceptor the
> same
> >>> thing?
> >>> * Does everyone using Spring know what " *The returned list should then
> >>> be added to the RestTemplate* " means? (I have no clue :-) but I am
> >>> Spring-ignorant.)
> >>>
> >>> Audit Catalog page:
> >>> The page mentions Products and Categories 3 times, every time saying
> "but
> >>> Log4j doesn't do anything with that". Why not just leave it out
> altogether
> >>> and not mention these?
> >>> Why is it called a Catalog? Perhaps explaining why this term is a good
> >>> name would help set the readers frame of thinking to understand the
> rest of
> >>> the page.
> >>> Also, do users need to create a catalog? Or is it something that
> emerges
> >>> automatically when one uses audit logging? What happens if you don't
> create
> >>> a catalog?
> >>>
> >>> Hope this is useful,
> >>> Remko
> >>>
> >>>
> >>> On Mon, Feb 5, 2018 at 2:35 PM, Ralph Goers <
> ralph.go...@dslextreme.com>
> >>> wrote:
> >>>
> >>>> Well I have good news and bad news. The bad news is that I forgot my
> wife
> >>>> and I were having people over for the super bowl so I didn’t have as
> much
> >>>> time as I had hoped and I wasn’t able to run the Log4j 2.11.0 release
> build.
> >>>>
> >>>> The good news is that I think Log4j Audit V1.0 is about ready for a
> >>>> release. I have published the web site at
> https://rgoers.github.io/log4j
> >>>> -audit/index.html <https://rgoers.github.io/log4j-audit/index.html>.
> >>>> Some parts of the site will have problems since it hasn’t been
> released but
> >>>> I hope you could take a look at it and review it before a release
> vote is
> >>>> attempted.
> >>>>
> >>>> You should also feel free to ask me questions here, but if it isn’t
> clear
> >>>> then I expect the web site needs more work.
> >>>>
> >>>> Ralph
> >>>
> >>>
> >>>
> >
>

Reply via email to