Anvil: log from a resource
The raw Open API version of this page is Open API: log from a plugin.
A resource writes its lines into CATIA Magic's own Log4j log, under a category it names itself. The
logging and format packages carry everything this page uses, and both are on the runtime side of
what Anvil publishes.
Take one logger
ResourceLog.of answers with the logger for a category and caches it, so a second call for the same
name answers with the same logger. Keep it in a top-level property and reuse it:
import com.mbseconsulting.anvil.format.IdStyle
import com.mbseconsulting.anvil.format.fString
import com.mbseconsulting.anvil.logging.ResourceLog
private val log = ResourceLog.of("ACME")
log.info { "applied ${stereotype.fString()} to ${element.fString(IdStyle.SHORT)}" }Name the category for the resource, short and symbolic — ACME rather than a class or a package
name. CATIA Magic prints it as %c, a reader greps for it, and one configuration entry raises it.
A resource that runs the auto-stereotyping engine passes the same logger to its AutoStereotypeRuleSet,
so the engine and the tracer write under the resource's category too.
Pass a lambda, never a built string
Every method takes () -> String. CATIA Magic's root logger sits at info, so a debug or trace
call costs one boolean while nobody is listening and builds nothing:
log.debug { "candidates: ${candidates.fString(IdStyle.SHORT)}" }Choose a level
| Method | Carries |
|---|---|
trace { } | High-volume detail, such as one line per model event |
debug { } | Detail for diagnosing a problem, invisible until someone raises the category |
info { } | Something the resource did that a reader of the log would want to know |
warn(throwable) { } | Something went wrong and the resource carried on |
error(throwable) { } | Something went wrong and the resource could not carry on |
warn and error take the throwable first, before the lambda, and it defaults to null:
log.error(exception) { "could not apply ${stereotype.fString()}" }
log.warn { "no profile found for \"${project.name}\"" }Render model values with fString
toString on a model element answers with an implementation class and a hash. fString answers with
the metaclass, the name, the applied stereotypes and the identifier:
Class "Concept A" «Concept» (_2026x_1_328c0658_1786288981600_428316_3213)fString accepts any value, so a collection, a map or a plain string renders through the same call,
and every read inside it is guarded: an element the committing transaction has just deleted renders
as a placeholder rather than throwing out of the log call.
Anvil: render model values covers the IdStyle argument, what each
field of the rendering means, and hString for a Message Window sink.
Attribute a block of work
forAction sets Log4j's action_name for the duration of a block, so every line inside carries the
name in CATIA Magic's own pattern and no message repeats it:
log.forAction("Auto-stereotype") { applications.forEach(::applyOne) }The previous value is restored on the way out, because a resource shares that context with the tool.
Read the lines back
CATIA Magic configures Log4j at <install>/data/log4j2.xml. One entry raises the resource's category
and touches nothing else:
<Logger name="ACME" level="debug"/>The tool's configuration carries monitorInterval="30", so the entry takes effect within thirty
seconds and needs no restart. Leave additivity at its default. Every custom entry in the tool's own
configuration sets additivity="false", and copying that idiom takes the resource's lines out of the
tool log rather than adding to them.
What not to reach for
println and System.out write to the console that launched the process, which a modeller running
an installed CATIA Magic never sees.
A logger obtained straight from LogManager.getLogger loses the caller location Anvil
prepends and the lambda guard that keeps a failed message from failing its caller. It also lands
under a category nobody knows to raise.
Nothing in this project reaches the Message Window. GUILog.log(String) delegates to
log(message, open = true), which opens the notification window on every call, so a resource logging
once per model change puts that window in front of the modeller once per edit. A resource that must
interrupt a modelling session makes that decision itself, at the moment it interrupts, and calls
GUILog with the flag it wants — or reaches for Notify.of(category), which builds that sink for
you as a transient balloon instead of a window — see Anvil: notify a
modeller.
hString renders a model element as an mdel:// anchor for a resource that builds such a sink; the
Message Window turns the anchor into a link that selects the element.
Related
- Open API: log from a plugin — the raw Open API call this page wraps.
- Anvil: render model values —
fString,hStringandIdStylein full. - Anvil: trace model events — one line per model event, written under this same category once it is raised.
- Anvil: write an auto-stereotype rule — the engine logs one
line per applied stereotype under this same category, and its tracer writes at
debug. - Anvil: notify a modeller — the balloon a resource shows for the same category, logged first and shown second.
- The
catia-magic:loggingskill states the same rules for an agent editing this code. It ships from thembseconsultingmarketplace rather than from a file in this repository.