Logging

The Maltego logging system allows transforms to communicate status, progress, and errors to users during execution. Log messages appear in the Maltego client's output window.

Log Methods

Access logging through context.log:

from maltego.server import register_transform, MaltegoContext
from maltego.entities import Phrase


@register_transform(...)
async def my_transform(entity: Phrase, context: MaltegoContext) -> Phrase:
    context.log.inform("Starting transform...")
    context.log.debug("Debug details here")
    context.log.partial("Progress update...")
    context.log.fatal("Error occurred!")


    return Phrase(entity.value)

inform()

General informational messages for status updates:

context.log.inform("Transform started")
context.log.inform(f"Processing {count} items")
context.log.inform("Transform completed successfully")

Use for:

• Transform start/completion messages
• General status updates
• Summary information

debug()

Detailed technical information for troubleshooting:

context.log.debug(f"Input value: {entity.value}")
context.log.debug(f"API response: {response.status_code}")
context.log.debug(f"Processing entity ID: {entity_id}")

Use for:

• Variable values and state
• API responses and requests
• Technical details helpful for debugging

partial()

Progress updates during long-running operations:

context.log.inform(f"Processing {total} items...")


for i, item in enumerate(items, 1):
    percent = i * 100 // total
    context.log.partial(f"Processing {item}... ({i}/{total} - {percent}%)")
    # Process item


context.log.inform(f"Completed: {len(results)} items processed")

Use for:

• Progress percentages
• Current step in multi-step processes
• Batch processing updates

fatal()

Error messages that indicate problems. Use to report errors while still returning partial results:

for url in urls:
    try:
        data = await fetch_url(url)
        results.append(data)
    except Exception as e:
        errors.append(url)
        context.log.debug(f"Failed: {url} - {e}")


if errors:
    context.log.fatal(f"Failed to process {len(errors)} URLs")


context.log.inform(f"Success: {len(results)}, Failed: {len(errors)}")
return results  # Return partial results

Use for:

• Error notifications
• Failed operations
• Validation failures

``fatal()`` logs an error message but does **not** stop the transform. To stop execution, return ``None`` or raise a ``MaltegoException``.

Complete Example

Run maltego-transforms start my_project to create a new project from the template. See transforms/logging_example.py for runnable examples of all logging patterns covered in this guide.

Best Practices

1. Be concise - Users scan logs quickly; keep messages short and clear
2. Use appropriate levels - Don't spam with debug messages; use partial for progress
3. Include context - Add relevant values to messages (counts, IDs, etc.)
4. Log errors meaningfully - Include what failed and why
5. Track progress - For operations >2 seconds, show progress updates