diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/decorated-class.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/decorated-class.png new file mode 100644 index 000000000..9599d15fb Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/decorated-class.png differ diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/decorator.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/decorator.png new file mode 100644 index 000000000..9d8afe7a2 Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/decorator.png differ diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/dependency-graph.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/dependency-graph.png new file mode 100644 index 000000000..299f72df4 Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/dependency-graph.png differ diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/intercepted-class.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/intercepted-class.png new file mode 100644 index 000000000..135b16ac8 Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/intercepted-class.png differ diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/interceptor.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/interceptor.png new file mode 100644 index 000000000..2660a4dca Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/interceptor.png differ diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/producer.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/producer.png new file mode 100644 index 000000000..8494770c5 Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/producer.png differ diff --git a/enterprise/docs/modules/ROOT/assets/images/dev-console/scoped-bean.png b/enterprise/docs/modules/ROOT/assets/images/dev-console/scoped-bean.png new file mode 100644 index 000000000..751d8117d Binary files /dev/null and b/enterprise/docs/modules/ROOT/assets/images/dev-console/scoped-bean.png differ diff --git a/enterprise/docs/modules/ROOT/nav.adoc b/enterprise/docs/modules/ROOT/nav.adoc index d059a8a2d..f024bafbc 100644 --- a/enterprise/docs/modules/ROOT/nav.adoc +++ b/enterprise/docs/modules/ROOT/nav.adoc @@ -527,6 +527,7 @@ **** xref:Technical Documentation/Payara Server Documentation/Extensions/gRPC Support/Usage.adoc[Usage] ** xref:Technical Documentation/Payara Server Documentation/Payara Server Docker Image.adoc[Payara Server Docker Image] ** xref:Technical Documentation/Payara Server Documentation/Payara InSight.adoc[Payara InSight] +** xref:Technical Documentation/Payara Server Documentation/Payara Dev Console.adoc[Payara Dev Console] ** Diagnostics and Troubleshooting *** xref:Technical Documentation/Payara Server Documentation/Diagnostics and Troubleshooting/Diagnostics Tool.adoc[Diagnostics Tool] ** Upgrade Guide diff --git a/enterprise/docs/modules/ROOT/pages/Technical Documentation/Payara Server Documentation/Payara Dev Console.adoc b/enterprise/docs/modules/ROOT/pages/Technical Documentation/Payara Server Documentation/Payara Dev Console.adoc new file mode 100644 index 000000000..51b78570c --- /dev/null +++ b/enterprise/docs/modules/ROOT/pages/Technical Documentation/Payara Server Documentation/Payara Dev Console.adoc @@ -0,0 +1,378 @@ +[[payara-dev-console]] += Payara Dev Console +:ordinal: 3 + +Payara Dev Console provides an integrated development console for inspecting and debugging Jakarta EE applications running on Payara Platform. + +It is designed to help developers understand CDI wiring, bean lifecycle behavior, interception chains, injection resolution, and security metadata during development. + +The diagnosis console exposes runtime insights directly from the container, making it easier to troubleshoot configuration problems, dependency issues, and unexpected application behavior without requiring external profiling tools. + +--- + +== Overview + +When Payara Dev Console is enabled, Payara instruments key Jakarta EE subsystems and presents structured inspection views through the Dev Console UI. + +This includes visibility into: + +* CDI bean discovery and resolution +* Scoped lifecycle activity +* Dependency wiring and injection diagnostics +* Interceptors and decorators applied at runtime +* Observer event registrations +* Security annotation usage + +These insights are especially useful when diagnosing: + +* Unsatisfied or ambiguous injections +* Unexpected bean recreation +* Circular dependencies +* Missing or misapplied interceptors +* Decorators not being activated +* REST security misconfiguration + +--- + +== CDI Diagnosis + +The CDI Diagnosis console provides detailed visibility into the container’s bean registry and runtime behavior. + +=== Bean Registry Inspection + +Developers can explore all beans discovered in the deployment, including: + +* Scope annotations (`@ApplicationScoped`, `@RequestScoped`, etc.) +* Qualifiers and stereotypes +* Bean types and declaring classes +* Producer-based and synthetic beans + +This helps validate whether CDI beans are being discovered and registered correctly. + +--- + +=== Scoped Bean Lifecycle Analysis + +Payara Dev Console includes scope-aware lifecycle summaries showing: + +* Total beans per scope +* Created vs active instances +* Destroyed lifecycle events +* Runtime scope distribution + +image::dev-console/scoped-bean.png[Scoped Bean] + +This makes it easier to detect scope misuse, such as excessive request-scoped recreation or unintended application-scoped singletons. + +--- + +=== Dependency Graph Visualization + +For selected beans, the console can render an interactive dependency graph showing: + +* Direct injection relationships +* Downstream dependencies +* Circular dependency detection +* Resolution paths between beans + +image::dev-console/dependency-graph.png[Dependency Graph] + +This helps developers understand complex CDI wiring in larger applications. + +--- + +== Injection Diagnostics + +One of the most common sources of deployment and runtime errors in CDI applications is incorrect injection resolution. + +Payara Dev Console provides a dedicated Injection Points console that reports: + +* Total injection points discovered +* Resolved injection points +* Unsatisfied dependencies +* Ambiguous resolution conflicts + +--- + +=== Unsatisfied Injection Detection + +Unsatisfied injection points occur when no bean matches the required type and qualifiers. + +The console reports: + +* Required injection type +* Declared qualifiers +* Status (`UNSATISFIED`) +* Resolution details explaining the mismatch + +This is especially useful when debugging: + +* Missing bean discovery +* Incorrect qualifier usage +* Disabled alternatives +* Unavailable producers + +--- + +=== Ambiguous Injection Reporting + +When multiple beans match the same injection point, CDI reports an ambiguity error. + +Payara Dev Console highlights these conflicts so developers can apply: + +* Proper qualifiers +* Specialization +* Alternatives + +--- + +== Producer Diagnosis + +The Producers view provides insight into producer methods and fields registered in the container. + +It includes: + +* Producer origin class and member signature +* Produced types +* Runtime production counts +* Disposal tracking (when applicable) + +image::dev-console/producer.png[Producer] + +This is useful when validating custom resource factories, configuration producers, or integration beans. + +--- + +== Interceptors & Decorators + +Payara Dev Console provides dedicated inspection views for CDI interception infrastructure. + +--- + +=== Interceptor Discovery + +Developers can review: + +* All enabled interceptors +* Binding annotations and activation rules +* Execution priorities +* Invocation statistics + +image::dev-console/interceptor.png[Interceptor] + +This helps confirm that transactional, security, or tracing interceptors are applied correctly. + +--- + +=== Intercepted Class Analysis + +In addition to listing interceptors, Payara Dev Console shows exactly which application classes are intercepted at runtime. + +This view provides: + +* Intercepted bean classes discovered in the deployment +* Interceptors applied to each class +* Per-class interceptor resolution counts + +image::dev-console/intercepted-class.png[Intercepted Class] + +This is useful when troubleshooting: + +* Interceptors not firing as expected +* Unexpected framework interceptors being activated +* Multiple bindings applied simultaneously + +--- + +=== Decorator Discovery + +Decorators wrap CDI beans with additional behavior. + +The Decorators view allows developers to inspect: + +* All decorators enabled in the application +* Decorated interfaces and bean types +* Delegate injection targets +* Associated scopes and lifecycle activity + +image::dev-console/decorator.png[Decorator] + +This helps validate decorator resolution and activation. + +--- + +=== Decorated Class Mapping + +The Decorated Classes view highlights: + +* Which classes are currently being decorated +* Decorators applied to each target type +* Number of decorator layers involved + +image::dev-console/decorated-class.png[Decorated Class] + +This is especially helpful in applications where decorators are enabled indirectly through extensions or libraries. + +--- + +== Observer Event Diagnosis + +CDI event-driven applications rely heavily on observer methods. + +Payara Dev Console provides an Observer Events console exposing metadata such as: + +* Observed event types +* Observer bean classes +* Qualifier information +* Reception mode (`ALWAYS`, conditional) +* Transaction phase participation + +This allows developers to verify: + +* Observers are registered correctly +* Events are delivered in the expected transaction phase +* Qualifier mismatches are not preventing notifications + +--- + +== REST Payara Dev Console + +The REST diagnosis console provides visibility into Jakarta REST registrations. + +It includes: + +=== Resource Discovery + +Developers can inspect: + +* Registered REST resource classes +* Available REST methods and verbs +* Application path mappings + +This helps confirm that REST endpoints are being deployed correctly. + +--- + +=== Exception Mapper Visibility + +The console also lists registered exception mappers, allowing developers to verify: + +* Custom error handling activation +* Mapper priority and applicability + +--- + +== Security Annotation Audit + +Payara Dev Console includes a Security Audit view that inspects Jakarta Security annotations applied across REST endpoints. + +It highlights usage of: + +* `@RolesAllowed` +* `@PermitAll` +* `@DenyAll` + +For each secured entry, the console displays: + +* HTTP method and resource path +* Applied security annotation +* Declaring class and method + +This provides a quick way to review security configuration during development and detect unsecured or unintentionally restricted endpoints. + +--- + +== Runtime Metrics Dashboard + +In addition to application introspection, Payara Dev Console provides a lightweight Metrics Dashboard. + +This includes: + +* Loaded/unloaded class counts +* Heap and non-heap memory usage +* Live and daemon thread tracking +* CPU load summaries +* Auto-refresh monitoring during development + +This offers quick feedback on runtime pressure without requiring external profilers. + +--- + +== Asadmin Commands + +The Dev Console can be configured and managed using dedicated `asadmin` commands. + +--- + +=== Get Dev Console Configuration + +Retrieves the effective Dev Console configuration for the specified target. + +[source,shell] +---- +asadmin get-dev-console-configuration --target +---- + +Returned properties include: + +* `enabled` +* `dynamic` +* `endpoint` +* `virtualServers` +* `securityEnabled` +* `roles` + +--- + +=== Set Dev Console Configuration + +Updates Dev Console configuration attributes. + +[source,shell] +---- +asadmin set-dev-console-configuration \ + --enabled=true|false \ + --dynamic=true|false \ + --endpoint=/dev \ + --virtualServers=server \ + --securityEnabled=true|false \ + --roles=admin +---- + +--- + +== Accessing the Dev Console + +Once enabled, the Dev Console becomes accessible through the configured endpoint. + +For example, with the default configuration, it can be reached at: + +---- +http://localhost:8080/dev +---- + +--- + +== Usage Notes + +* Payara Dev Console is intended for development and debugging environments. +* It provides deep container introspection and should not be enabled unnecessarily in production deployments. +* When diagnosing deployment issues, redeploying the application may be required to refresh instrumentation state. + +--- + +== Summary + +Payara Dev Console provides an integrated troubleshooting console covering: + +* CDI bean discovery and lifecycle visibility +* Dependency graphs and scoped activity +* Interceptor and decorator mapping +* Observer event inspection +* Security annotation auditing +* Injection resolution failure reporting +* Lightweight runtime metrics + +These capabilities reduce the need for manual logging and significantly improve the developer experience when debugging Jakarta EE applications in Payara. + +--- \ No newline at end of file