Quick Start
New to LogViewer plugins? Start here:
Overview
LogViewer supports a plugin architecture that allows extending functionality without modifying the core application. Plugins are dynamically loaded shared libraries that use a C-ABI interface for maximum compatibility and ABI stability across different compilers and versions.
Plugins export standard C functions like Plugin_Create, Plugin_CreateMainPanel, etc.
C-ABI Plugin Architecture
All modern LogViewer plugins use the C-ABI approach for better compatibility and reduced ABI dependencies. Plugins export standard C functions that the application calls to create and manage plugin instances. This is the only supported method for plugin development going forward.
Required Exports:
extern "C" {
}
EXPORT_PLUGIN_SYMBOL const char * Plugin_GetMetadataJson(PluginHandle pluginHandle)
Definition AIProviderPlugin.cpp:491
EXPORT_PLUGIN_SYMBOL PluginHandle Plugin_Create()
Definition AIProviderPlugin.cpp:350
EXPORT_PLUGIN_SYMBOL void Plugin_Destroy(PluginHandle h)
Definition AIProviderPlugin.cpp:365
#define EXPORT_PLUGIN_SYMBOL
Definition IPlugin.hpp:65
Optional Panel Exports:
extern "C" {
EXPORT_PLUGIN_SYMBOL void* Plugin_CreateRightPanel(PluginHandle,
void* parent,
const char* settings);
}
EXPORT_PLUGIN_SYMBOL void * Plugin_CreateBottomPanel(PluginHandle pluginHandle, void *parentWidget, const char *)
Definition AIProviderPlugin.cpp:444
EXPORT_PLUGIN_SYMBOL void * Plugin_CreateLeftPanel(PluginHandle pluginHandle, void *parentWidget, const char *)
Definition AIProviderPlugin.cpp:455
EXPORT_PLUGIN_SYMBOL void * Plugin_CreateMainPanel(PluginHandle pluginHandle, void *parentWidget, const char *)
Definition AIProviderPlugin.cpp:434
Logger Callback:
extern "C" {
}
EXPORT_PLUGIN_SYMBOL void Plugin_SetLoggerCallback(PluginHandle h, PluginLogFn logFn)
Definition AIProviderPlugin.cpp:358
The application calls Plugin_SetLoggerCallback immediately after Plugin_Create to provide a logging function that plugins can use.
Why callback-based logging: the original logger was header-only with static variables, which caused ODR violations across DLL boundaries — each shared library got its own copy of the global, so the application's registration was invisible inside the plugin. Passing the logging function in as a callback after Plugin_Create avoids this: it works across DLL boundaries, has no ABI dependencies, and keeps the API simple for plugin authors.
Migrating from the old IPlugin interface
Older LogViewer plugins used a C++ IPlugin virtual interface. This has been fully replaced by the C-ABI exports described above:
class IPlugin {
virtual bool Initialize() = 0;
virtual void Shutdown() = 0;
};
extern "C" {
}
To migrate an old IPlugin-based plugin: remove the IPlugin inheritance, export the C-ABI functions instead, store plugin state behind the opaque PluginHandle, and use find_package(LogViewer CONFIG REQUIRED) in CMakeLists.txt. Follow the Basic Plugin Example for the current pattern.
The internal PluginManager still notifies observers about plugin lifecycle events (loaded, enabled, disabled, …) — see PLUGIN_OBSERVER_PATTERN.md for that host-side architecture (not needed for plugin authors).
Plugin Logging
Plugins can log messages to the application's logging system using the provided callback:
#include "PluginLoggerC.h"
void PluginLogger_Log(int level, const char *message)
Definition PluginLoggerC.cpp:12
Log Levels:
PLUGIN_LOG_TRACE: Detailed debug information
PLUGIN_LOG_DEBUG: Debug messages
PLUGIN_LOG_INFO: Informational messages
PLUGIN_LOG_WARN: Warning messages
PLUGIN_LOG_ERROR: Error messages
PLUGIN_LOG_CRITICAL: Critical errors
How It Works:
- Application calls
Plugin_Create() to instantiate the plugin
- Application calls
Plugin_SetLoggerCallback(handle, &AppLogFunc) to provide logging callback
- Plugin calls
PluginLogger_Register(logFn) to store the callback
- Plugin uses
PluginLogger_Log(level, message) to log messages
- Messages appear in application logs with
[plugin] prefix
Plugin Types
The system supports several plugin types:
- Parser: Custom log file format parsers
- Filter: Custom filtering strategies
- Exporter: Export logs to different formats
- Analyzer: Advanced log analysis tools
- Connector: Remote log source connections (e.g., SSH, databases)
- Visualizer: Custom visualization components
- AIProvider: AI-powered log analysis
- Custom: Generic plugins for other purposes
Plugin Architecture
C Plugin Structure
Plugins are C++ classes that export C-ABI functions. Internally, plugins can use any C++ features, but the external interface must be pure C.
Example Plugin Class:
class MyPlugin {
public:
MyPlugin() { }
~MyPlugin() { }
PluginMetadata GetMetadata() const {
return {
.id = "my_plugin",
.name = "My Plugin",
.version = "1.0.0",
.type = PluginType::Custom
};
}
bool Initialize() { return true; }
void Shutdown() { }
};
}
Definition IFieldConversionPlugin.hpp:8
Plugin Metadata
Plugins return metadata as JSON via Plugin_GetMetadataJson:
{
"id": "my_plugin",
"name": "My Plugin",
"version": "1.0.0",
"api_version": "1.0.0",
"description": "Plugin description"
}
See the SDK Quick Reference for the current config.json format and required fields.
Plugin Manager
The PluginManager singleton handles plugin lifecycle:
- Discovery: Scan plugins directory for
.dll/.so/.dylib files
- Loading: Load plugin via
LoadLibrary/dlopen
- Logger Setup: Call
Plugin_SetLoggerCallback to provide logging
- Initialization: Call
Plugin_Initialize on loaded plugins
- Panel Creation: Call
Plugin_CreateXxxPanel functions for UI
- Lifecycle: Initialize, shutdown plugins via C-ABI functions
Plugin Loading Process
Plugin_Initialize(handle);
Plugin_Shutdown(handle);
nlohmann::json json
Definition FilterSerializer.cpp:9
void AppPluginLog(int level, const char *message)
Definition PluginManager.cpp:35
Creating a Plugin
⚠️ For detailed plugin development instructions, see:
The sections below provide architectural context. Developers should follow the SDK guides above.
1. Create Plugin Class
Create a C++ class with your plugin logic:
class MyPlugin {
private:
std::string m_lastError;
public:
MyPlugin() = default;
~MyPlugin() = default;
PluginMetadata GetMetadata() const {
return {
.id = "my_plugin",
.name = "My Plugin",
.version = "1.0.0",
.apiVersion = "1.0.0",
.author = "Your Name",
.description = "Plugin description",
.type = PluginType::Custom
};
}
bool Initialize() {
return true;
}
void Shutdown() {
}
const std::string& GetLastError() const { return m_lastError; }
};
}
2. Export C-ABI Functions
Export required C functions:
extern "C" {
try {
return new plugin::MyPlugin();
} catch (...) {
return nullptr;
}
}
if (h) {
delete reinterpret_cast<plugin::MyPlugin*>(h);
}
}
if (h && logFn) {
}
}
if (!h) return nullptr;
auto*
plugin =
reinterpret_cast<plugin::MyPlugin*
>(h);
auto meta =
plugin->GetMetadata();
nlohmann::json j;
j["id"] = meta.id;
j["name"] = meta.name;
j["version"] = meta.version;
std::string str = j.dump();
char*
result = (
char*)malloc(str.size() + 1);
if (result) {
memcpy(result, str.c_str(), str.size() + 1);
}
}
}
void PluginLogger_Register(PluginLogFn fn)
Definition PluginLoggerC.cpp:7
std::string result
Definition OllamaClient.cpp:144
3. Build as Shared Library
Use the SDK approach:
cmake_minimum_required(VERSION 3.22)
project(MyPlugin)
find_package(LogViewer CONFIG REQUIRED)
find_package(Qt6 COMPONENTS Core Widgets REQUIRED)
add_library(my_plugin MODULE src/MyPlugin.cpp)
target_link_libraries(my_plugin
PRIVATE
LogViewer::plugin_api
Qt6::Widgets
)
set_target_properties(my_plugin PROPERTIES PREFIX "")
configure_file(config.json.in config.json @ONLY)
add_custom_command(TARGET my_plugin POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy
${CMAKE_CURRENT_BINARY_DIR}/config.json
$<TARGET_FILE_DIR:my_plugin>/config.json
)
See SDK Quick Reference for the complete CMakeLists.txt template.
Available Plugins
Basic Example Plugin
Location: examples/BasicPlugin/
A minimal plugin demonstrating the C-ABI interface. Perfect for learning plugin development.
Features:
- All required plugin exports
- Plugin state management
- Logger callback integration
- Config.json metadata
Build Instructions:
cd examples/BasicPlugin
cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/sdk/lib/cmake
cmake --build build
AI Provider Plugin
Location: plugins/ai/
Provides AI-powered log analysis capabilities with multiple provider support.
Features:
- Multiple AI provider support (Ollama, OpenAI, Anthropic, Google Gemini, xAI Grok, LM Studio)
- Three UI panels: configuration (left), analysis (main), chat (bottom)
- Real-time log analysis and pattern detection
- Interactive chat with AI about logs
Build Option: Enabled by default when building LogViewer with plugins
Dependencies: libcurl, Qt6, nlohmann_json, fmt
See AI_PROVIDER_PLUGIN.md for detailed documentation.
Plugin Configuration
Plugins are configured through the application's configuration dialog:
- Plugin List: View all discovered plugins
- Enable/Disable: Toggle plugin activation
- Auto-Load: Configure plugins to load automatically on startup
- Settings: Plugin-specific configuration via left panel UI
Plugin settings are stored in JSON format in the application's configuration directory.
Plugin Directory Structure
LogViewer/
├── src/
│ ├── plugin_api/
│ │ ├── PluginC.h # C-ABI function typedefs
│ │ ├── PluginLoggerC.h # Logger API for plugins
│ │ ├── PluginEventsC.h # Events API
│ │ └── PluginKeyEncryptionC.h # Key encryption API
│ └── application/
│ └── plugins/
│ ├── PluginManager.hpp # Plugin manager
│ └── PluginManager.cpp
└── plugins/
└── ai/ # AI provider plugin
├── CMakeLists.txt
├── AIProviderPlugin.hpp
├── AIProviderPlugin.cpp
└── lib/ # Plugin dependencies
Platform-Specific Notes
macOS
- Plugin extension:
.dylib
- Use
dlopen() for dynamic loading
- Plugins built with:
add_library(plugin SHARED)
Linux
- Plugin extension:
.so
- Use
dlopen() for dynamic loading
- Requires
-fPIC compiler flag
Windows
- Plugin extension:
.dll
- Use
LoadLibrary() for dynamic loading
- Use
EXPORT_PLUGIN_SYMBOL __declspec(dllexport) for exports
Troubleshooting
Plugin Not Loading
- Check plugin file exists in plugins directory
- Verify plugin exports
Plugin_Create function: nm -g plugin.so | grep Plugin_Create
- Check dependencies are satisfied
- Review application logs for error messages
- Ensure plugin is built with compatible compiler/ABI
Logger Issues
- Verify
Plugin_SetLoggerCallback is exported
- Check that
PluginLogger_Register is called in the callback
- Use
PLUGIN_LOG_INFO level for visibility (DEBUG may be filtered)
- Look for
[plugin] prefix in application logs
Panel Not Appearing
- Check that
Plugin_CreateXxxPanel export exists
- Verify function returns non-null
QWidget*
- Check plugin logs for error messages during panel creation
- Ensure parent widget is passed correctly
Best Practices
- Error Handling: Always check return values, use try-catch in C++ code
- Logging: Use
PluginLogger_Log extensively for debugging
- Dependencies: Keep external dependencies minimal
- Versioning: Use semantic versioning for plugins
- Documentation: Provide clear plugin documentation
- Testing: Test plugin loading/unloading multiple times
- Thread Safety: Ensure plugins are thread-safe
- Resource Cleanup: Properly cleanup in
Plugin_Destroy
Key Design Decisions
- C-ABI only — no C++ interfaces are exported, for maximum compatibility across compilers/versions.
- Callback-based logging — solves the ODR violation across DLL boundaries described above.
- Opaque handles —
PluginHandle is void*, hiding the plugin's internal implementation.
- Qt widget panels — UI is created as
QWidget*, cast to void* at the C-ABI boundary.
- JSON metadata — returned as a string for a flexible, forward-compatible schema.
Future Enhancements
- Plugin hot-reloading support
- Plugin marketplace/repository
- Automatic dependency resolution
- Plugin sandboxing for security
- Plugin API versioning
- Remote plugin updates