improve recipes

Author: zspitzer

docs/recipes/logging.md

@@ -18,27 +18,15 @@
 }
 -->
 
-# Logging in Lucee
+# Logging
 
-Lucee's logging system is a powerful and flexible framework designed to provide insights into your application’s behavior.
+Logging helps you monitor errors, track events, and troubleshoot your applications. Lucee's logging system is built on Log4j2, giving you flexible control over what gets logged, where it goes, and how it's formatted.
 
-By configuring logs, you can monitor errors, track events, and troubleshoot efficiently.
+You can configure log levels to control verbosity, choose appenders to direct output (console, files, databases, or custom destinations like Kafka), and select layouts to format the output.
 
-## Why Logging?
+## Log Levels
 
-Logging is an essential practice for maintaining reliable and performant applications. It allows you to:
-
-- Monitor runtime behavior and identify issues.
-- Gain insights into application usage and performance.
-- Maintain an audit trail of events and actions.
-
-Lucee supports various log types (or levels), enabling you to control the verbosity and focus of your logs.
-
-Additionally, you can configure logging destinations and formats to integrate seamlessly with your infrastructure.
-
-## How to Use Log Levels?
-
-Log levels (or types) categorize log entries based on their importance or severity. Lucee supports the following log levels in decreasing order of severity:
+In decreasing order of severity:
 
 - **fatal**: Severe errors causing premature termination.
 - **error**: Runtime errors or unexpected conditions that require attention.
@@ -47,17 +35,13 @@ Log levels (or types) categorize log entries based on their importance or severi
 - **debug**: Detailed information helpful for debugging issues.
 - **trace**: The most detailed information for fine-grained troubleshooting.
 
-### Configuring Log Level Thresholds
+### Log Level Thresholds
 
-You can configure the minimum log level (threshold) for each logger in the **Lucee Administrator** or directly in the configuration file (`.CFConfig.json`).
+Configure minimum log level per logger in **Lucee Administrator** or `.CFConfig.json`. Setting threshold to `warn` records only warnings, errors, and fatal - ignoring `info`, `debug`, and `trace`.
 
-For instance, setting a threshold of `warn` means only warnings, errors, and fatal logs are recorded, ignoring `info`, `debug`, and `trace` logs.
+### Redirecting Logs to Console
 
-This allows you to start with minimal logging in production and increase verbosity (e.g., to `debug`) for deeper analysis when needed.
-
-### Redirecting all logs to the console
-
-Lucee 6.2 supports the following environment variables which allow overriding the log levels and appender, which is great for debugging and Docker
+Since Lucee 6.2, override log levels and appender via environment variables:
 
 ```bash
 LUCEE_LOGGING_FORCE_LEVEL=info
@@ -66,7 +50,7 @@ LUCEE_LOGGING_FORCE_APPENDER=console
 
 ### Adding or Modifying Logs
 
-You can add, modify, or remove loggers in the **Lucee Administrator** or directly edit the `.CFConfig.json` file. Below is an example configuration:
+Configure in **Lucee Administrator** or `.CFConfig.json`:
 
 ```json
 "loggers": {
@@ -95,42 +79,30 @@ You can add, modify, or remove loggers in the **Lucee Administrator** or directl
 }
 ```
 
-### Internals: Powered by Log4j2
-
-Lucee's logging system is powered by **Log4j2**, providing robust support for Appenders and Layouts.
-
-You can extend Lucee logging by using any Appender or Layout supported by Log4j2.
+### Internals: Log4j2
 
----
+Powered by **Log4j2** - extend with any Log4j2 Appender or Layout.
 
-## Built-in Support for Appenders and Layouts
+## Appenders and Layouts
 
 ### Built-in Appenders
 
-Lucee comes with built-in support for the following Appenders:
-
-- **console**: Logs output to the console, ideal for debugging in development or server environments.
-- **datasource**: Logs to a database table, allowing structured storage and querying of log data.
-- **resource**: Logs to a virtual filesystem endpoint, which can include local filesystems or external systems like **S3**, FTP, etc.
+- **console**: Output to console
+- **datasource**: Store in database table
+- **resource**: Write to virtual filesystem (local, S3, FTP, etc.)
 
 ### Built-in Layouts
 
-Lucee also provides the following Layouts for customizing log output:
-
-- **classic**: Produces traditional CFML-compatible output.
-- **datadog**: Formats logs for direct ingestion into **Datadog**.
-- **html**: Outputs logs in an HTML format suitable for browser-based debugging.
-- **json**: Generates logs in structured JSON format (uses Log4j2's JSONAppender internally).
-- **pattern**: Allows custom patterns for maximum flexibility.
-- **xml**: Outputs logs in structured XML format.
-
----
+- **classic**: Traditional CFML-compatible output
+- **datadog**: Datadog ingestion format
+- **html**: HTML format for browser debugging
+- **json**: Structured JSON (uses Log4j2's JSONAppender)
+- **pattern**: Custom patterns
+- **xml**: Structured XML
 
-## Extending Logging with Custom Appenders and Layouts
+## Custom Appenders and Layouts
 
-In addition to the built-in Appenders and Layouts, Lucee supports custom configurations using third-party libraries.
-
-Here’s how you can define custom Appenders and Layouts:
+Extend with third-party libraries:
 
 ### Custom Appender Configuration
 
@@ -171,29 +143,23 @@ Here’s how you can define custom Appenders and Layouts:
 }
 ```
 
-This configuration sends logs to a Kafka topic with a custom pattern Layout.
-
----
+Sends logs to a Kafka topic with custom pattern layout.
 
-## Using the `<cflog>` Tag
+## Using `<cflog>`
 
-Lucee supports logging through the `<cflog>` tag, which allows you to send log entries to specific loggers. The tag is available in both **HTML-style** and **script-style** syntax.
-
-### Examples
-
-#### HTML-Style Syntax
+### Tag Syntax
 
 ```html
 <cflog log="application" type="warn" text="Warning: Something went wrong!">
 ```
 
-#### Script-Style Syntax (Migration)
+### Script Syntax
 
 ```javascript
 log log="application" type="warn" text="Warning: Something went wrong!";
 ```
 
-#### Script-Style Syntax (Function)
+### Function Syntax
 
 ```javascript
 try {
@@ -204,8 +170,4 @@ catch(e) {
 }
 ```
 
-(Due to the existing math log function, the cf prefix is still required here, unlike with other tags in script.)
-
-Lucee's `<cflog>` tag supports various attributes, including `log`, `type`, `text`, and `exception`. Using these attributes, you can customize log entries to suit your application's needs.
-
-Lucee’s extensible logging framework offers flexibility for integrating with diverse infrastructures, enhancing monitoring, debugging, and auditing capabilities. By leveraging built-in features and custom configurations, you can adapt the logging system to your application's unique needs.
+Note: Due to the existing math `log` function, the `cf` prefix is required here unlike other tags in script.

docs/recipes/lucene-search.md

@@ -24,18 +24,13 @@
 
 # Lucene 3 Extension
 
-The Lucene 3 Extension introduces significant enhancements to Lucee's search capabilities, including vector-based semantic search, hybrid search combining keyword and vector approaches, and improved content chunking for more relevant results.
+The Lucene 3 Extension brings modern search capabilities to Lucee, including vector-based semantic search that understands meaning rather than just matching keywords. You can use traditional keyword search, pure vector search, or combine both in hybrid mode for best results.
 
-## Overview
+Key features:
 
-Lucene 3 is a major update to Lucee's search functionality, bringing modern search techniques to your applications. This version introduces:
-
-- Vector-based semantic search using document embeddings
-- Hybrid search combining traditional keyword search with vector search
-- Enhanced content chunking with passage extraction
-- Improved relevance scoring and result highlighting
-
-These features enable more natural language understanding in search operations and provide better support for AI augmentation through Retrieval-Augmented Generation (RAG) patterns.
+- **Vector search** - find conceptually similar content using embeddings
+- **Hybrid search** - combine keyword and vector approaches
+- **Content chunking** - extract relevant passages for RAG (Retrieval-Augmented Generation) patterns
 
 ## Requirements
 

docs/recipes/migrate.from.classic-to-modern-local-scope.md

@@ -17,31 +17,25 @@
 
 # Migrating from Classic to Modern Local Scope Mode
 
-Lucee offers two different modes for managing unscoped variables within functions: Classic and Modern.
+Lucee offers two modes for handling unscoped variables in functions: Classic and Modern.
 
-This document explains the differences between these modes and provides a structured approach for migrating from Classic to Modern mode.
-
-Simply switching to `localmode=true`, either per function or Application wide, will dramatically boost the performance of your Lucee applications, but requires testing.
+Switching to `localmode=true` (per function or application-wide) dramatically boosts performance, but requires testing.
 
 ## Understanding Local Scope Modes
 
-The "Local scope mode" setting defines how variables with no explicit scope are handled within functions:
+The local scope mode setting defines how unscoped variables are handled in functions:
 
-* **Classic Mode (CFML Default)**: Unscoped variables are stored in the variables scope, unless the key already exists in one of the function's local scopes (arguments or local).
-* **Modern Mode**: Unscoped variables are always stored in the local scope, regardless of whether they exist elsewhere.
+- **Classic Mode** (CFML default): Unscoped variables go to `variables` scope, unless the key exists in `arguments` or `local`.
+- **Modern Mode**: Unscoped variables always go to `local` scope.
 
 ## Why Migrate to Modern Mode?
 
-Modern mode offers several advantages:
-
-1. **Thread Safety**: Variables are isolated to the function instance, preventing race conditions when component instances are shared across requests.
-2. **Predictable Behavior**: All unscoped variables behave the same way, making code more intuitive and easier to maintain.
-3. **Performance**: Local scope lookups are typically faster than cascading scope resolution.
+- **Thread Safety**: Variables isolated to function instance - prevents race conditions with shared components
+- **Predictable Behavior**: All unscoped variables behave the same way
+- **Performance**: Local scope lookups are faster than cascading scope resolution
 
 ### Classic Mode Race Condition Example
 
-Consider this component when running in Classic mode:
-
 ```cfml
 component {
     function createToken(id) {
@@ -52,39 +46,29 @@ component {
 }
 ```
 
-If this component is stored in application scope and used across multiple concurrent requests, `token` becomes a shared variable. This creates a race condition where multiple threads could overwrite each other's values.
+If this component is in application scope and used concurrently, `token` becomes shared - multiple threads can overwrite each other's values.
 
 ## Configuring Local Scope Mode
 
-Local scope mode can be configured at several levels:
-
-### 1. Server Level (Lucee Administrator)
+### Server Level (Lucee Administrator)
 
-Under "Settings > Scope", set "Local scope mode" to either "Modern" or "Classic".
+Under "Settings > Scope", set "Local scope mode" to "Modern" or "Classic".
 
-### 2. Server Configuration (.CFConfig.json)
+### Server Configuration (.CFConfig.json)
 
 ```json
 {
     "localScopeMode": "modern"
 }
 ```
 
-Or:
-
-```json
-{
-    "localScopeMode": "classic"
-}
-```
-
-### 3. Application Level (Application.cfc)
+### Application Level (Application.cfc)
 
 ```cfml
 this.localMode = "modern"; // or "classic"
 ```
 
-### 4. Function Level
+### Function Level
 
 ```cfml
 function test() localMode="modern" {
@@ -94,29 +78,20 @@ function test() localMode="modern" {
 
 ## Migration Strategy: Using Cascading Write Logging
 
-Switching directly to Modern mode may break existing applications that rely on Classic behavior. A safer approach is to:
+Switching directly to Modern mode may break existing applications. A safer approach:
 
-1. Enable variable scope cascading write logging
-2. Identify and fix all occurrences of unscoped variables
+1. Enable cascading write logging
+2. Fix all unscoped variable occurrences
 3. Switch to Modern mode
 
 ### Step 1: Enable Cascading Write Logging
 
-Set the following environment variables or system properties (This setting only applies to Lucee 6.2.1.82 and above):
-
-**Environment Variable:** `LUCEE_CASCADING_WRITE_TO_VARIABLES_LOG`
-**System Property:** `-Dlucee.cascading.write.to.variables.log`
-
-This specifies the log name where cascading write detections will be recorded.
-
-You can also customize the log level (default is DEBUG):
-
-**Environment Variable:** `LUCEE_CASCADING_WRITE_TO_VARIABLES_LOGLEVEL`
-**System Property:** `-Dlucee.cascading.write.to.variables.loglevel`
+Set environment variables or system properties (Lucee 6.2.1.82+):
 
-Valid log levels include: DEBUG, INFO, WARN, ERROR.
+- `LUCEE_CASCADING_WRITE_TO_VARIABLES_LOG` / `-Dlucee.cascading.write.to.variables.log` - log name for detections
+- `LUCEE_CASCADING_WRITE_TO_VARIABLES_LOGLEVEL` / `-Dlucee.cascading.write.to.variables.loglevel` - log level (DEBUG, INFO, WARN, ERROR)
 
-Example configuration:
+Example:
 
 ```
 # Environment variables
@@ -130,31 +105,22 @@ LUCEE_CASCADING_WRITE_TO_VARIABLES_LOGLEVEL=INFO
 
 ### Step 2: Analyze Logs and Modify Code
 
-Monitor your application logs for entries like:
+Log entries look like:
 
 ```
 Variable Scope Cascading Write Detected: The variable [token] is being implicitly written to the variables scope at [MyComponent.cfc:42]. This occurs when no explicit scope (such as local, arguments, or variables) is specified in the assignment.
 ```
 
-For each occurrence, decide whether to:
+For each occurrence, add explicit scope:
 
-1. **Add explicit `variables` scope** (if the variable should remain in the component's variables scope):
-
-```cfml
-variables.token = createUUID();
-```
-
-2. **Add explicit `local` scope** (if the variable should be function-local):
-
-```cfml
-local.token = createUUID();
-```
+- `variables.token = createUUID();` - if it should remain component-level
+- `local.token = createUUID();` - if it should be function-local
 
 ### Common Patterns Requiring Attention
 
 #### Component Properties
 
-Properties meant to be stored at the component level need an explicit variables scope:
+Properties stored at the component level need explicit `variables` scope:
 
 ```cfml
 // Before
@@ -170,7 +136,7 @@ function init(datasourceName) {
 
 #### Local Counters and Temporary Variables
 
-Variables that should be local to a function call:
+Variables local to a function call:
 
 ```cfml
 // Before
@@ -196,31 +162,14 @@ function processItems(items) {
 
 ### Step 3: Test Thoroughly
 
-After updating your code:
-
 1. Test your application thoroughly
-2. Verify that all functionality works correctly
-3. Look for unexpected behaviors or errors
-4. Make sure you no longer get any log entries
+2. Verify all functionality works correctly
+3. Check for unexpected behaviors or errors
+4. Ensure no more log entries appear
 
 ### Step 4: Disable Logging and Switch to Modern Mode
 
-Once all code has been updated and tested:
-
-1. Disable the cascading write logging by removing the environment variables or system properties:
-
-   ```
-   # Remove environment variables
-   unset LUCEE_CASCADING_WRITE_TO_VARIABLES_LOG
-   unset LUCEE_CASCADING_WRITE_TO_VARIABLES_LOGLEVEL
-
-   # Or remove system properties from startup configuration
-   # -Dlucee.cascading.write.to.variables.log
-   # -Dlucee.cascading.write.to.variables.loglevel
-   ```
-
-2. Switch to Modern mode at your preferred configuration level (server, application, or function).
-
-## Conclusion
+Once all code is updated and tested:
 
-Migrating to Modern mode improves thread safety and code predictability, but requires careful examination of existing code. Using cascading write logging helps identify potential issues before they become problems, allowing for a smooth transition.
+1. Remove the environment variables or system properties
+2. Switch to Modern mode at your preferred configuration level