diff --git a/docs/administration/ai-providers.md b/docs/administration/ai-providers.md index 041324e..f3c8259 100644 --- a/docs/administration/ai-providers.md +++ b/docs/administration/ai-providers.md @@ -1,12 +1,13 @@ --- sidebar_position: 3 description: Configure AI providers in Anaphora for intelligent report analysis - GPT-5.2, Claude 4.5, Grok 4, DeepSeek V3, Qwen3, Llama 4, and self-hosted options. -keywords: [AI providers, GPT-5, Claude 4.5, Grok 4, DeepSeek V3, Qwen3, Llama 4, vLLM, LLM integration, AI analysis] +keywords: [ AI providers, GPT-5, Claude 4.5, Grok 4, DeepSeek V3, Qwen3, Llama 4, vLLM, LLM integration, AI analysis ] --- # AI Providers -Configure AI providers to enable intelligent analysis, content generation, and anomaly detection in your reports. Anaphora supports any provider implementing the OpenAI-compatible API specification. +Configure AI providers to enable intelligent analysis, content generation, and anomaly detection in your reports. +Anaphora supports any provider implementing the OpenAI-compatible API specification. ## Overview @@ -32,196 +33,25 @@ flowchart LR api -- "Analysis result" --> job ``` -## OpenAI-Compatible API - -Anaphora works with any provider implementing the OpenAI API specification. This includes: - -| Provider | Description | Self-Hosted | -|----------|-------------|-------------| -| **OpenAI** | GPT-5.2, GPT-5.1 models | No | -| **Anthropic** | Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 | No | -| **xAI** | Grok 4, Grok 3 models | No | -| **Azure OpenAI** | Microsoft-hosted OpenAI models | No | -| **DeepSeek** | DeepSeek-V3.2, cost-effective reasoning | No | -| **vLLM** | Self-hosted open-source models | Yes | -| **Ollama** | Local model runner | Yes | -| **LM Studio** | Desktop model runner | Yes | - ## Configuration ### Adding a Provider -1. Navigate to **Settings** > **AI Providers** +1. Navigate to **AI Providers** 2. Click **Add Provider** 3. Configure the connection: -| Field | Description | Example | -|-------|-------------|---------| -| **Name** | Identifier for this provider | `Production GPT-5` | -| **API Endpoint** | OpenAI-compatible base URL | `https://api.openai.com/v1` | -| **API Key** | Authentication token | `sk-...` (stored encrypted) | -| **Default Model** | Model to use if not specified | `gpt-5.2` | +| Field | Description | Example | +|--------------|-------------------------------------------------------|--------------------------------| +| **Name** | Identifier for this provider | `Production GPT-5` | +| **Provider** | Type of AI provider | `OpenAI`, `DeepSeek`, `Custom` | +| **Endpoint** | OpenAI-compatible base URL (Only for custom provider) | `https://api.openai.com/v1` | +| **API Key** | Authentication token | `sk-...` (stored encrypted) | +| **Model** | Model to use. Needs API key to fetch suggestions. | `gpt-5.2` | 4. Test the connection 5. Save -### Multiple Providers - -Configure multiple providers for different use cases: - -``` -Provider: DeepSeek-V3 -├── Endpoint: https://api.deepseek.com/v1 -├── Model: deepseek-v3.2 -└── Use for: Complex analysis, reasoning tasks - -Provider: vLLM-Qwen -├── Endpoint: http://vllm.internal:8000/v1 -├── Model: Qwen3-32B-Instruct -└── Use for: High-volume processing, cost control - -Provider: OpenAI-GPT5 -├── Endpoint: https://api.openai.com/v1 -├── Model: gpt-5.2 -└── Use for: Critical reports, best quality - -Provider: Anthropic-Claude -├── Endpoint: https://api.anthropic.com/v1 -├── Model: claude-sonnet-4.5 -└── Use for: Coding analysis, agentic tasks -``` - -### Multiple Models per Provider - -Each provider can expose multiple models: - -| Provider | Available Models | -|----------|-----------------| -| OpenAI | `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.1` | -| Anthropic | `claude-opus-4.5`, `claude-sonnet-4.5`, `claude-haiku-4.5` | -| xAI | `grok-4`, `grok-4-heavy`, `grok-3`, `grok-3-mini` | -| DeepSeek | `deepseek-v3.2`, `deepseek-r1` | -| vLLM | Depends on deployed models (Qwen3, Llama 4, etc.) | - -## Provider Types - -### DeepSeek - -Cost-effective models with strong reasoning capabilities. DeepSeek-V3.2 integrates thinking directly into tool-use. - -**Configuration:** -``` -Name: DeepSeek -Endpoint: https://api.deepseek.com/v1 -API Key: sk-xxxxx -Default Model: deepseek-v3.2 -``` - -**Available Models:** -- `deepseek-v3.2` — Latest flagship, thinking + tool-use integration -- `deepseek-v3.1` — Hybrid model combining V3 and R1 strengths -- `deepseek-r1` — Advanced reasoning, complex analysis - -### vLLM (Self-Hosted) - -Run open-source models on your infrastructure for data privacy and cost control. - -**Configuration:** -``` -Name: vLLM Internal -Endpoint: http://vllm-server.internal:8000/v1 -API Key: (optional, depends on deployment) -Default Model: Qwen3-32B-Instruct -``` - -**Popular Models for vLLM:** -- `Qwen3-32B-Instruct` — Strong general purpose, 128K context -- `Qwen3-235B-A22B` — Massive MoE model (22B active params) -- `Llama-4-Maverick` — Meta's multimodal MoE (17B active, 400B total) -- `Llama-4-Scout` — 10M context window (17B active, 109B total) -- `Qwen3-Coder-480B` — State-of-the-art coding (35B active) - -**Benefits:** -- Complete data privacy — data never leaves your infrastructure -- No per-token costs after initial setup -- Customizable model selection -- Low latency for internal networks - -### OpenAI - -Direct integration with OpenAI's API. GPT-5.2 is the current flagship with Instant, Thinking, and Pro variants. - -**Configuration:** -``` -Name: OpenAI -Endpoint: https://api.openai.com/v1 -API Key: sk-proj-xxxxx -Default Model: gpt-5.2 -``` - -**Available Models:** -- `gpt-5.2` — Latest flagship, best for coding and agentic tasks -- `gpt-5.2-codex` — Optimized for agentic coding workflows -- `gpt-5.1` — Previous generation (Instant and Thinking variants) - -### Anthropic Claude - -State-of-the-art models for coding, agents, and complex reasoning. Claude 4.5 series offers excellent cost-performance. - -**Configuration:** -``` -Name: Anthropic -Endpoint: https://api.anthropic.com/v1 -API Key: sk-ant-xxxxx -Default Model: claude-sonnet-4.5 -``` - -**Available Models:** -- `claude-opus-4.5` — Flagship, long-horizon autonomous tasks ($5/$25 per M tokens) -- `claude-sonnet-4.5` — Best balance of quality and cost ($3/$15 per M tokens) -- `claude-haiku-4.5` — Fast and efficient ($1/$5 per M tokens) - -### xAI Grok - -Strong reasoning models with real-time knowledge. Grok 4 is the latest flagship with 1M token context. - -**Configuration:** -``` -Name: xAI Grok -Endpoint: https://api.x.ai/v1 -API Key: xai-xxxxx -Default Model: grok-4 -``` - -**Available Models:** -- `grok-4` — Latest flagship, strong reasoning and tool use -- `grok-4-heavy` — Maximum capability variant -- `grok-3` — Previous generation, good cost-performance balance -- `grok-3-mini` — Fast responses, lower cost - -### Azure OpenAI - -Enterprise deployment through Microsoft Azure. - -**Configuration:** -``` -Name: Azure OpenAI -Endpoint: https://your-resource.openai.azure.com -API Key: xxxxx -Default Model: gpt-5 (deployment name) -``` - -## Space-Level Configuration - -AI Providers are configured per Space for isolation: - -| Space | AI Provider | Use Case | -|-------|-------------|----------| -| Production | OpenAI GPT-5.2 | Critical reports, highest quality | -| Development | vLLM Qwen3 | Testing, iteration | -| Client-Acme | DeepSeek V3.2 | Cost-effective analysis | -| Client-Beta | Claude Sonnet 4.5 | Balanced quality and cost | - ### Provider Inheritance - Each Space can have its own AI provider configuration @@ -230,25 +60,29 @@ AI Providers are configured per Space for isolation: ## Using AI in Jobs -### Composer Integration +### Job Capture Integration -Add AI-generated content blocks in the Composer: +Use AI actions in the job actions: -1. Add an **AI Analysis** block -2. Select the analysis type: - - **Summary** — Condense captured data - - **Trends** — Identify patterns over time - - **Anomalies** — Highlight unusual values - - **Custom** — Provide your own prompt +1. Edit or create a job +2. Navigate to the **Capture** tab +3. Enable advanced mode to use actions. +4. Add **AI** action +5. Configure: -3. Configure the prompt (for custom analysis) -4. Preview the output +| Field | Description | +|---------------|-----------------------------------------| +| Variable Name | Name of the variable to store AI output | +| Provider | Select the AI provider to use | +| Prompt | Define the prompt with instructions | +| Output type | Text, HTML, Number | +| Context | Choose what to include as context | ### Example: Dashboard Summary ``` -Block: AI Analysis -Type: Summary +Context: Dashboard snapshot showing system performance metrics +Type: Text Prompt: "Summarize the key metrics from this dashboard, highlighting any values that exceed normal ranges." @@ -261,70 +95,14 @@ Output: "System performance remains stable with 99.8% uptime. ### Example: Anomaly Detection ``` -Block: AI Analysis -Type: Anomaly Detection Context: Error rate visualization captured from Kibana +Type: Number +Prompt: "Identify any anomalies in the error rate data. Respond with 0 if none found. Return 1 if anomalies are detected." -Output: "⚠️ Anomaly detected: Error rate spiked to 4.2% between - 09:15-09:45 UTC, significantly above the 0.5% baseline. - This correlates with the deployment at 09:12 UTC visible - in the deployment timeline panel." +Output: 0 ``` -## Best Practices - -### Provider Selection - -| Use Case | Recommended Provider | -|----------|---------------------| -| **Security-sensitive data** | Self-hosted vLLM (Qwen3, Llama 4) | -| **Cost-sensitive high volume** | DeepSeek V3.2 or vLLM | -| **Best quality analysis** | OpenAI GPT-5.2 or Claude Opus 4.5 | -| **Coding and agentic tasks** | Claude Sonnet 4.5 or GPT-5.2-Codex | -| **Compliance requirements** | Azure OpenAI or self-hosted | - -### Prompt Engineering - -For consistent results: - -- Be specific about the desired output format -- Provide context about what the data represents -- Specify the audience (technical vs. executive) -- Include examples of good output when possible - -### Cost Management - -- Use appropriate models for each task (don't use Opus 4.5 for simple summaries — use Haiku 4.5) -- Set token limits for responses -- Monitor usage through provider dashboards -- Consider self-hosted options for high-volume use cases (Qwen3, Llama 4) - -### Reliability - -- Configure fallback providers for critical jobs -- Test AI features in development Spaces first -- Set reasonable timeout values -- Handle AI failures gracefully (jobs should complete even if AI fails) - -## Troubleshooting - -### Connection Issues - -| Issue | Solution | -|-------|----------| -| Connection timeout | Check endpoint URL, verify network access | -| 401 Unauthorized | Verify API key is correct and active | -| 429 Rate Limited | Reduce request frequency, upgrade plan | -| Model not found | Check model name matches provider's offerings | - -### Quality Issues - -| Issue | Solution | -|-------|----------| -| Poor analysis quality | Improve prompts, try different model | -| Inconsistent outputs | Add more specific instructions | -| Missing context | Ensure captured data is included | -| Hallucinations | Use more constrained prompts | +Use the output to add a condition in your job workflow for alerting. ## Next Steps diff --git a/docs/administration/authentication/index.md b/docs/administration/authentication/index.md index 496c14b..96c0703 100644 --- a/docs/administration/authentication/index.md +++ b/docs/administration/authentication/index.md @@ -1,114 +1,64 @@ --- sidebar_position: 1 description: Configure Anaphora authentication - local users, LDAP, SAML SSO, OpenID Connect, and session management. -keywords: [authentication, LDAP, SAML, SSO, OpenID Connect, OIDC, session management, RBAC] +keywords: [ authentication, LDAP, SAML, SSO, OpenID Connect, OIDC, session management, RBAC ] --- # Authentication -Configure user authentication and access control for Anaphora. The platform supports enterprise-standard authentication methods for secure access. +Configure user authentication and access control for Anaphora. The platform supports enterprise-standard authentication +methods for secure access. ## Authentication Methods -| Method | Description | Best For | -|--------|-------------|----------| -| [Local](/administration/authentication/local) | Built-in username/password | Small teams, testing | -| [LDAP](/administration/authentication/ldap) | Active Directory integration | Enterprise Windows environments | -| [SAML](/administration/authentication/saml) | Single Sign-On via SAML 2.0 | Okta, Azure AD, OneLogin | -| [OIDC](/administration/authentication/oidc) | OpenID Connect providers | Google, Auth0, Keycloak | +| Method | Description | Best For | +|-----------------------------------------------|------------------------------|---------------------------------| +| [Local](/administration/authentication/local) | Built-in username/password | Small teams, testing | +| [LDAP](/administration/authentication/ldap) | Active Directory integration | Enterprise Windows environments | +| [SAML](/administration/authentication/saml) | Single Sign-On via SAML 2.0 | Okta, Azure AD, OneLogin | +| [OIDC](/administration/authentication/oidc) | OpenID Connect providers | Google, Auth0, Keycloak | ## Roles and Permissions Anaphora uses role-based access control (RBAC). -### Built-in Roles +### User types -| Role | Permissions | -|------|-------------| -| **Admin** | Full access: users, settings, all Spaces | -| **Editor** | Create and edit jobs, run reports | -| **Viewer** | View reports and job status only | +Anaphora has two main user types: System users and normal users. System users will have global access and can manage the +Anaphora instance. While normal users will be assigned to specific spaces with permissions scoped to those spaces. -### Permission Details - -| Permission | Admin | Editor | Viewer | -|------------|-------|--------|--------| -| View reports | Yes | Yes | Yes | -| Create jobs | Yes | Yes | No | -| Edit jobs | Yes | Yes | No | -| Delete jobs | Yes | No | No | -| Manage delivery interfaces | Yes | Yes | No | -| Manage users | Yes | No | No | -| Manage Spaces | Yes | No | No | -| System settings | Yes | No | No | - -### Custom Roles - -Create custom roles with specific permissions: - -1. Go to **Settings** > **Roles** -2. Click **Create Role** -3. Select permissions to include -4. Save and assign to users - -## Session Management - -Administrators have visibility and control over user sessions. - -### Active Sessions - -View all active user sessions: - -| Information | Description | -|-------------|-------------| -| User | Logged-in user | -| IP Address | Client IP | -| Login Time | When session started | -| Last Activity | Most recent action | -| Device/Browser | Client information | +| User Type | Description | Methods | +|-----------------|--------------------------------------------|---------| +| **System user** | Full global access, manage system settings | Local | +| **Normal user** | Access and manage resources within spaces | All | -### Session Controls +### Space Permissions -| Action | Description | -|--------|-------------| -| **View sessions** | See all active sessions | -| **Force logout** | Terminate specific session | -| **Logout all** | Terminate all sessions for a user | +Users are assigned permissions within specific spaces: -### Session Policies +| Permission | Description | +|---------------|------------------------------------| +| **Admin** | Full access within assigned spaces | +| **ReadWrite** | Create and edit jobs, run reports | +| **Readonly** | View reports and job status only | -Configure session behavior: - -| Setting | Description | -|---------|-------------| -| Session timeout | Auto-logout after inactivity | -| Maximum sessions | Limit concurrent sessions per user | -| Remember me duration | Extended session lifetime | - -### Security Events - -Audit log captures authentication events: - -- Login success/failure -- Logout events -- Password changes -- Session terminations -- Permission changes - -## Best Practices - -### Security - -- Use SSO when available for centralized access control -- Require strong passwords for local accounts -- Review active sessions regularly -- Set appropriate session timeouts - -### Enterprise Integration +### Permission Details -- Use dedicated service accounts for LDAP binding -- Map groups to roles for automated permission management -- Test authentication changes in staging first +| Rights | System User | Space Admin | Space ReadWrite | Space Readonly | +|----------------------------|-------------|-------------|-----------------|----------------| +| View reports | Yes | Yes | Yes | Yes | +| View runs | Yes | Yes | Yes | Yes | +| Manage jobs | Yes | Yes | Yes | No | +| Manage delivery interfaces | Yes | Yes | No | No | +| Manage AI providers | Yes | Yes | No | No | +| Manage users | Yes | No | No | No | +| Manage spaces | Yes | No | No | No | +| Global settings | Yes | No | No | No | + +### Add User Permissions + +See the [Spaces](/administration/spaces) documentation for details on assigning users to spaces with specific +permissions. ## Next Steps diff --git a/docs/administration/authentication/ldap.md b/docs/administration/authentication/ldap.md index c9c4d79..3ccc579 100644 --- a/docs/administration/authentication/ldap.md +++ b/docs/administration/authentication/ldap.md @@ -1,13 +1,15 @@ --- sidebar_position: 2 description: Configure LDAP and Active Directory authentication for Anaphora enterprise deployments. -keywords: [LDAP, Active Directory, AD, directory integration, enterprise authentication] +keywords: [ LDAP, Active Directory, AD, directory integration, enterprise authentication ] --- # LDAP / Active Directory -Connect to your enterprise directory for centralized user management. Supports Microsoft Active Directory, OpenLDAP, and other LDAP-compliant directories. +Connect to your enterprise directory for centralized user management. Supports Microsoft Active Directory, OpenLDAP, and +other LDAP-compliant directories. ![](images/ldap.png) + ## Overview LDAP integration provides: @@ -19,85 +21,40 @@ LDAP integration provides: ## Configuration -Navigate to **Settings** > **Authentication** > **LDAP** to configure. - -### Connection Settings - -| Field | Description | Example | -|-------|-------------|---------| -| Server URL | LDAP server address | `ldaps://ldap.company.com:636` | -| Base DN | Search base for users | `dc=company,dc=com` | -| Bind DN | Service account for queries | `cn=anaphora,ou=service,dc=company,dc=com` | -| Bind Password | Service account password | (stored encrypted) | -| Connection Timeout | Max connection wait time | `10` seconds | -| Read Timeout | Max response wait time | `30` seconds | - -### User Search Settings - -| Field | Description | Example | -|-------|-------------|---------| -| User Base DN | Where to search for users | `ou=users,dc=company,dc=com` | -| User Filter | LDAP query for users | `(&(objectClass=user)(sAMAccountName={0}))` | -| Username Attribute | Attribute for login | `sAMAccountName` | - -### Group Settings (Optional) - -| Field | Description | Example | -|-------|-------------|---------| -| Group Base DN | Where to search for groups | `ou=groups,dc=company,dc=com` | -| Group Filter | Query for user's groups | `(&(objectClass=group)(member={0}))` | -| Group Name Attribute | Attribute for group name | `cn` | - -## Attribute Mapping - -Map LDAP attributes to Anaphora user properties: - -| Anaphora Field | Active Directory | OpenLDAP | -|----------------|------------------|----------| -| Username | `sAMAccountName` | `uid` | -| Email | `mail` | `mail` | -| Display Name | `displayName` | `cn` | -| Groups | `memberOf` | `memberOf` | - -### Mapping Configuration - -``` -Username Attribute: sAMAccountName -Email Attribute: mail -Display Name Attribute: displayName -Group Membership Attribute: memberOf -``` - -## Group-Based Roles - -Map LDAP groups to Anaphora roles for automatic permission assignment. - -### Example Mappings - -``` -LDAP Group: CN=Anaphora-Admins,OU=Groups,DC=company,DC=com - → Anaphora Role: Admin - -LDAP Group: CN=Anaphora-Editors,OU=Groups,DC=company,DC=com - → Anaphora Role: Editor +Navigate to **Settings** > **System Settings** > **Auth** > **LDAP** to configure. + +| Field | Description | Example | Required | +|---------------------|--------------------------------|----------------------------------------|----------| +| URL | LDAP server address | `ldap://ldap.forumsys.com:389` | Yes | +| Bind DN | Service account for binding | `cn=read-only-admin,dc=example,dc=com` | Yes | +| Bind credentials | Service account password | (stored securely) | Yes | +| Search base | Base DN for user search | `dc=example,dc=com` | Yes | +| Search filter | LDAP filter for user lookup | `uid={{username}}` | Yes | +| Group search base | Base DN for group search | `ou=groups,dc=example,dc=com` | No | +| Group search filter | LDAP filter for groups | `(member={{cn}})` | No | +| Group name property | Attribute for group name | `cn` | No | +| Reject unauthorized | Enforce TLS certificate checks | `false` (unchecked) | No | +| CA | Certificate authority | base64-encoded PEM | No | +| Key | Client private key | base64-encoded PEM | No | +| Certificate | Client certificate | base64-encoded PEM | No | + +### Group to Role Mapping + +Use the group search to retrieve LDAP groups and map them to Anaphora roles. +In the **group search filter**, use `{{}}` placeholders to reference attributes from the login user. +Use the **Group name property** to specify which attribute will be used as the mapped role name. -LDAP Group: CN=Anaphora-Viewers,OU=Groups,DC=company,DC=com - → Anaphora Role: Viewer -``` - -### Space Membership +### SSL/TLS Configuration -Map groups to Space access: +For secure connections use LDAPS (port 636): -``` -LDAP Group: CN=Team-Alpha,OU=Teams,DC=company,DC=com - → Space: Alpha Team Reports - → Role: Editor +| Protocol | Port | Security | +|----------|------|-------------------------------| +| LDAP | 389 | Unencrypted (not recommended) | +| LDAPS | 636 | SSL/TLS encrypted | +| StartTLS | 389 | Upgraded to TLS | -LDAP Group: CN=Team-Beta,OU=Teams,DC=company,DC=com - → Space: Beta Team Reports - → Role: Viewer -``` +Provide CA, Key, and Certificate fields for TLS client authentication if required by your LDAP server. ## Active Directory Specifics @@ -110,60 +67,12 @@ Create a dedicated service account for Anaphora: 3. Grant "Read all user information" permission 4. No need for admin privileges -### Common User Filters - -| Scenario | Filter | -|----------|--------| -| All users | `(&(objectClass=user)(sAMAccountName={0}))` | -| Enabled users only | `(&(objectClass=user)(sAMAccountName={0})(!(userAccountControl:1.2.840.113556.1.4.803:=2)))` | -| Specific OU | `(&(objectClass=user)(sAMAccountName={0})(memberOf=CN=Anaphora-Users,OU=Groups,DC=company,DC=com))` | - -### SSL/TLS Configuration - -Always use LDAPS (port 636) for secure connections: - -| Protocol | Port | Security | -|----------|------|----------| -| LDAP | 389 | Unencrypted (not recommended) | -| LDAPS | 636 | SSL/TLS encrypted | -| StartTLS | 389 | Upgraded to TLS | - -## Testing - -### Test Connection - -1. Click **Test Connection** to verify server connectivity -2. Verify "Connection successful" message -3. Check bind credentials are working - -### Test User Search - -1. Enter a known username -2. Click **Test User Search** -3. Verify user attributes are returned correctly - -### Test Authentication - -1. Enter test username and password -2. Click **Test Login** -3. Verify authentication succeeds and groups are retrieved - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Connection refused | Check server URL and port, verify firewall rules | -| Bind failed | Verify bind DN and password, check account is not locked | -| User not found | Check base DN and user filter, verify user exists | -| Groups not mapped | Verify group filter and group DN, check membership attribute | -| SSL certificate error | Import CA certificate or use trusted certificate | - ### Debug Mode Enable LDAP debug logging: -1. Go to **Settings** > **System** > **Logging** -2. Set LDAP log level to DEBUG +1. Go to **Settings** > **System Settings** > **General** > **General** +2. Set **Log Level** to `debug` 3. Reproduce the issue 4. Review logs for detailed LDAP communication diff --git a/docs/administration/authentication/local.md b/docs/administration/authentication/local.md index 6e077d1..76cf78c 100644 --- a/docs/administration/authentication/local.md +++ b/docs/administration/authentication/local.md @@ -1,19 +1,20 @@ --- sidebar_position: 1 description: Configure local authentication with Anaphora's built-in user database for username and password login. -keywords: [local authentication, user management, password policy, built-in users] +keywords: [ local authentication, user management, password policy, built-in users ] --- # Local Authentication + ![](images/local.png) -Default authentication using Anaphora's built-in user database. Ideal for small teams, testing environments, or deployments without enterprise identity providers. +Default authentication using Anaphora's built-in user database. Ideal for small teams, testing environments, or +deployments without enterprise identity providers. ## Overview Local authentication provides: - **Built-in user database** — No external dependencies -- **Password policies** — Configurable security requirements - **User management UI** — Easy administration - **Quick setup** — Works out of the box @@ -21,114 +22,55 @@ Local authentication provides: ### Adding Users -1. Navigate to **Settings** > **Users** -2. Click **Add User** +1. Navigate to **Settings** > **System Settings** > **Auth** > **Local** +2. Click **Add New User** 3. Enter username, email, and password -4. Assign roles and Space memberships -5. Save +4. Assign roles +5. Choose user type: Normal user or system user +6. Save ### User Properties -| Field | Description | Required | -|-------|-------------|----------| -| Username | Unique login identifier | Yes | -| Email | User email address | Yes | -| Display Name | Friendly name shown in UI | No | -| Password | Initial password | Yes | -| System Role | Access level for system settings | Yes | -| Roles | Assigned permissions | Yes | -| Spaces | Space memberships | No | +| Field | Description | Required | +|-------------|---------------------------------|----------| +| Username | Unique login identifier | Yes | +| Password | Initial password | Yes | +| Roles | Assigned permission groups | No | +| System Role | User or system user designation | Yes | ### System Role The **System Role** controls access to system-wide settings: -| Role | Description | -|------|-------------| -| **user** | Normal user, cannot access system settings | -| **system** | Can access and modify system settings | +| Role | Description | +|------------|--------------------------------------------------------------------------------| +| **user** | Normal user, cannot access system settings | +| **system** | Can access and modify system settings. Has automatically access to all spaces. | :::note -System settings include authentication configuration, AI providers, backup settings, and other global options. Most users should have the `user` role. +System settings include authentication configuration, space configuration, backup settings, and other global options. +Most users should have the `user` role. ::: -### Editing Users - -1. Go to **Settings** > **Users** -2. Click on the user to edit -3. Update properties as needed -4. Save changes +### Managing Local Users -### Removing Users - -1. Go to **Settings** > **Users** -2. Select the user to remove -3. Click **Delete** -4. Confirm deletion +All local users will be managed by the system user alone. Users cannot modify their own accounts. +System users can change the password or add roles to existing users. The system user can also delete the local users. :::warning Deleting a user removes their access immediately. Jobs created by the user will remain. ::: -## Password Policy - -Configure password requirements for local users: - -| Setting | Description | Recommended | -|---------|-------------|-------------| -| Minimum length | Required character count | 12+ characters | -| Complexity | Uppercase, lowercase, numbers, symbols | Enable all | -| Expiration | Force password change after X days | 90 days | -| History | Prevent reuse of recent passwords | Last 5 passwords | - -### Configuring Password Policy - -1. Go to **Settings** > **Security** -2. Navigate to **Password Policy** -3. Set requirements -4. Save - -### Password Change - -Users can change their own password: - -1. Click user menu (top right) -2. Select **Change Password** -3. Enter current and new password -4. Confirm - -Administrators can reset passwords: - -1. Go to **Settings** > **Users** -2. Select the user -3. Click **Reset Password** -4. Send reset link or set temporary password - ## When to Use Local Auth -| Scenario | Recommendation | -|----------|----------------| -| Small team (under 10 users) | Local auth is sufficient | -| Testing/development | Local auth for simplicity | -| No corporate IdP available | Local auth as primary method | -| Enterprise environment | Consider LDAP, SAML, or OIDC | -| Compliance requirements | Use enterprise SSO | - -## Best Practices - -- Use strong, unique passwords -- Enable password complexity requirements -- Set reasonable expiration periods -- Review user list regularly -- Remove inactive accounts promptly - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Forgot password | Admin can reset via Settings > Users | -| Account locked | Admin unlocks via Settings > Users | -| Login fails | Verify username and password case sensitivity | +| Scenario | Recommendation | +|-----------------------------|------------------------------| +| Small team (under 10 users) | Local auth is sufficient | +| Testing/development | Local auth for simplicity | +| No corporate IdP available | Local auth as primary method | +| System user | Local is required | +| Enterprise environment | Consider LDAP, SAML, or OIDC | +| Compliance requirements | Use enterprise SSO | ## Next Steps diff --git a/docs/administration/backup.md b/docs/administration/backup.md index ebcb341..f00d687 100644 --- a/docs/administration/backup.md +++ b/docs/administration/backup.md @@ -1,87 +1,80 @@ --- sidebar_position: 4 description: Back up Anaphora configuration, jobs, and reports. Schedule automatic backups and restore from backup files. -keywords: [Anaphora backup, configuration backup, disaster recovery, data protection, scheduled backup] +keywords: [ Anaphora backup, configuration backup, disaster recovery, data protection, scheduled backup ] --- # Backup -Protect your Anaphora configuration and data with regular backups. +Protect your Anaphora configuration and data with backups. There are three ways to back up your Anaphora instance: -## What to Back Up +1. **UI Export** - Use the UI to create and download backup files. +2. **API Export** - Use the API to programmatically export data. +3. **Docker Volume Backup** - For Docker deployments, back up the data volume directly. -| Component | Description | Priority | -|-----------|-------------|----------| -| Configuration | Jobs, templates, settings | Critical | -| Reports | Generated report files | Important | -| Database | User data, history | Critical | -| Credentials | Encrypted secrets | Critical | +:::tip +**UI Export** and **API Export** will only back up the configuration and data stored within Anaphora. +Report files are not included in these backups. So having a docker volume backup is recommended for complete data +protection. +::: -## Backup Methods +## UI Backup -### Built-in Backup +1. Access the **Settings** > **Data**. +2. Click **Export to file** to download a backup of the current configuration and data. +3. Store the backup file securely. -1. Navigate to **Settings** > **Backup** -2. Click **Create Backup** -3. Download the backup file -4. Store securely +### UI Import -### Scheduled Backups +1. Go to **Settings** > **Data** +2. Click **Import from file** +3. Upload the backup file -Configure automatic backups: - -| Setting | Description | -|---------|-------------| -| Frequency | Daily, weekly, monthly | -| Retention | Number of backups to keep | -| Location | Local or remote storage | -| Encryption | Encrypt backup files | - -### Docker Volume Backup +## Docker Volume Backup For Docker deployments, back up the data volume: ```bash docker run --rm \ - -v anaphora-data:/data \ + -v anaphora-content:/data/content \ + -v anaphora-storage:/data/storage \ -v $(pwd):/backup \ alpine tar czf /backup/anaphora-backup.tar.gz /data ``` -## Restore - -### From UI - -1. Go to **Settings** > **Backup** -2. Click **Restore** -3. Upload backup file -4. Confirm restoration - -### From Command Line +### Docker Volume Import ```bash docker run --rm \ - -v anaphora-data:/data \ + -v anaphora-content:/content \ + -v anaphora-storage:/storage \ -v $(pwd):/backup \ alpine tar xzf /backup/anaphora-backup.tar.gz -C / ``` -## Best Practices +## API Backup + +**Authentication**: Use basic auth headers with a system user. + +Get the backup via the following endpoint: + +``` +GET /guest/api/export +``` + +**Response**: A downloadable backup file in `.ana` format. -- Back up before upgrades -- Test restores regularly -- Store backups off-site -- Encrypt sensitive backups -- Document recovery procedures +### API Import -## Disaster Recovery +**Authentication**: Use basic auth headers with a system user. -Plan for disaster recovery: +Upload the backup file via the following endpoint: + +``` +POST /guest/api/import +``` -1. Identify critical data -2. Define recovery objectives (RTO/RPO) -3. Document procedures -4. Test recovery regularly +**Request Body**: `.ana` backup file as binary data. ## Next Steps diff --git a/docs/administration/images/space-selector.png b/docs/administration/images/space-selector.png new file mode 100644 index 0000000..6e49cc1 Binary files /dev/null and b/docs/administration/images/space-selector.png differ diff --git a/docs/administration/index.md b/docs/administration/index.md index a93efe5..af87732 100644 --- a/docs/administration/index.md +++ b/docs/administration/index.md @@ -1,138 +1,28 @@ --- sidebar_position: 6 description: Anaphora administration guide - configure authentication (LDAP, SAML, SSO), manage multi-tenant spaces, monitor system health, and backup data. -keywords: [Anaphora admin, LDAP authentication, SAML SSO, multi-tenant reporting, system monitoring, backup, RBAC] +keywords: [ Anaphora admin, LDAP authentication, SAML SSO, multi-tenant reporting, system monitoring, backup, RBAC ] --- # Administration - Security, Multi-Tenancy & Operations -Manage Anaphora's security, multi-tenancy, monitoring, and backups. This section covers enterprise features for managing users, permissions, and system health. +Manage Anaphora's security, multi-tenancy, monitoring, and backups. This section covers enterprise features for managing +users, permissions, and system health. ## Topics -| Topic | Description | -|-------|-------------| -| [Authentication](/administration/authentication/) | User authentication and access control | -| [Spaces](/administration/spaces) | Multi-tenant workspace management | -| [AI Providers](/administration/ai-providers) | Configure AI for intelligent analysis | -| [Self Monitoring](/administration/self-monitoring) | System health and metrics | -| [Backup](/administration/backup) | Data backup and recovery | +| Topic | Description | +|----------------------------------------------------|----------------------------------------| +| [Authentication](/administration/authentication/) | User authentication and access control | +| [Spaces](/administration/spaces) | Multi-tenant workspace management | +| [AI Providers](/administration/ai-providers) | Configure AI for intelligent analysis | +| [Self Monitoring](/administration/self-monitoring) | System health and metrics | +| [Backup](/administration/backup) | Data backup and recovery | -## Spaces: Multi-Tenant Isolation +## System User -Anaphora uses a **Spaces** concept to manage multi-tenancy and permissions effectively. - -### Shared-Nothing Architecture - -Spaces act as isolated containers with complete separation: - -```mermaid -flowchart TB - subgraph anaphora["Anaphora"] - subgraph spaceA["Space A"] - a1["Jobs"] - a2["Reports"] - a3["Delivery"] - a4["Users"] - end - subgraph spaceB["Space B"] - b1["Jobs"] - b2["Reports"] - b3["Delivery"] - b4["Users"] - end - subgraph spaceC["Space C"] - c1["Jobs"] - c2["Reports"] - c3["Delivery"] - c4["Users"] - end - end -``` - -- **Complete isolation** - Jobs, Delivery Interfaces, AI Providers, and reports cannot be shared between spaces -- **Copy support** - Items can be copied between spaces when needed -- **Independent configuration** - Each space has its own settings and retention policies - -### Use Cases for Spaces - -| Scenario | Implementation | -|----------|----------------| -| **Team separation** | Each team gets their own space with dedicated jobs | -| **Client isolation** | MSPs create separate spaces per client | -| **Environment separation** | Dev, staging, and production spaces | -| **Department boundaries** | Finance, Engineering, Marketing each have isolated spaces | - -## Role-Based Access Control (RBAC) - -Anaphora provides granular permissions through roles. - -### Permission Levels - -| Level | Capabilities | -|-------|-------------| -| **Read-only** | View jobs, reports, and settings | -| **Read-write** | Create and modify jobs, run reports | -| **Admin** | Full control including user management and space settings | - -### Assignment Options - -Permissions can be assigned to: - -- **Individual users** - Direct permission grants -- **Groups** - Permissions inherited by all group members -- **Roles** - Reusable permission sets - -## Authentication Methods - -Anaphora supports enterprise-standard authentication: - -| Method | Description | -|--------|-------------| -| [Local](/administration/authentication/local) | Built-in username/password authentication | -| [LDAP](/administration/authentication/ldap) | Active Directory and other LDAP directories | -| [SAML](/administration/authentication/saml) | SSO with Okta, Azure AD, OneLogin, etc. | -| [OIDC](/administration/authentication/oidc) | OAuth 2.0 / OpenID Connect providers | - -### Session Management - -Administrators can: - -- View all active sessions -- Force logout of specific users -- Set session timeout policies -- Monitor login history - -## System Monitoring - -Monitor Anaphora's health and performance: - -### Health Endpoint - -A dedicated endpoint for monitoring tools (Prometheus, Nagios, etc.): - -- System status and uptime -- Job execution statistics -- Error rates and failures -- Resource utilization - -### Alerting - -Configure alerts when: - -- Job execution error rates become too high -- System resources are constrained -- Authentication failures spike -- Delivery channels fail - -## Backup & Recovery - -Protect your Anaphora configuration and data: - -- **Full system backup** - Export all jobs, settings, and configurations -- **Scheduled backups** - Automate regular backup creation -- **Point-in-time recovery** - Restore to a specific backup -- **Migration support** - Move between Anaphora instances +The first user created during setup is the system administrator with full privileges. Only system admins can access and +manage the global settings. ## Next Steps diff --git a/docs/administration/self-monitoring.md b/docs/administration/self-monitoring.md index 08c2696..4d3fe67 100644 --- a/docs/administration/self-monitoring.md +++ b/docs/administration/self-monitoring.md @@ -1,92 +1,34 @@ --- sidebar_position: 3 description: Monitor Anaphora health, performance, and job metrics. Configure alerts, access logs, and integrate with Prometheus. -keywords: [self monitoring, health check, Prometheus, metrics, job monitoring, performance, Anaphora monitoring] +keywords: [ self monitoring, health check, Prometheus, metrics, job monitoring, performance, Anaphora monitoring ] --- # Self Monitoring -Monitor Anaphora's health, performance, and operational metrics. +Monitor Anaphora's health, job and delivery success. ![](images/self-monitoring.png) -## Dashboard -Access the monitoring dashboard at **Settings** > **Monitoring**. +## Health Monitoring -## Key Metrics +Access the monitoring settings at **Settings** > **Application** > **Health Monitoring**. -### System Health +### Setup Health Alerts -| Metric | Description | -|--------|-------------| -| Uptime | Time since last restart | -| Memory | Current memory usage | -| CPU | Processor utilization | -| Disk | Storage consumption | +Configure email alerts when the system detects changes in job health status. -### Job Metrics - -| Metric | Description | -|--------|-------------| -| Jobs Active | Currently running jobs | -| Jobs Scheduled | Total scheduled jobs | -| Success Rate | Percentage of successful runs | -| Avg Duration | Average job execution time | - -### Delivery Metrics - -| Metric | Description | -|--------|-------------| -| Deliveries/Hour | Reports sent per hour | -| Delivery Success | Successful delivery rate | -| Queue Depth | Pending deliveries | - -## Alerts - -Configure alerts for system issues: - -1. Go to **Monitoring** > **Alerts** -2. Set thresholds for key metrics -3. Configure notification channel -4. Enable the alert - -### Recommended Alerts - -- Job failure rate > 10% -- Memory usage > 85% -- Disk usage > 90% -- Delivery queue > 100 - -## Logs - -Access system logs: -- Application logs -- Job execution logs -- Error logs -- Audit logs - -### Log Levels - -| Level | Description | -|-------|-------------| -| ERROR | Failures requiring attention | -| WARN | Potential issues | -| INFO | Normal operations | -| DEBUG | Detailed troubleshooting | - -## Prometheus Endpoint - -Export metrics to Prometheus: - -``` -GET /metrics -``` +1. Enable **Health Alerts**. +2. Select a delivery interface and recipient email. +3. Set **Health Check Frequency**: how often to check job health. +4. Set **Maximum Notification Frequency**: minimum time between alerts (Optional). +5. Click **Save**. ## Health API Query Anaphora's health status programmatically: ``` -GET /api/health +GET /guest/api/health ``` ### Response Format @@ -94,20 +36,6 @@ GET /api/health ```json { "jobs": [ - { - "id": "533aeb70-efcc-43cc-8953-78f9c8fdc728", - "name": "Kibana Dashboard Snapshot", - "description": "Takes a snapshot of a dashboard", - "cron": "5 4 * * *", - "healthStatus": "green", - "recentRuns": [ - { "runAt": "2026-01-15T04:05:00.050Z", "state": "success" }, - { "runAt": "2026-01-14T04:05:00.040Z", "state": "success" }, - { "runAt": "2026-01-13T04:05:00.043Z", "state": "success" }, - { "runAt": "2026-01-12T04:05:00.049Z", "state": "success" }, - { "runAt": "2026-01-11T04:05:00.044Z", "state": "success" } - ] - }, { "id": "79cf54b6-df32-4b09-84f4-708ecc72b7bc", "name": "Kibana Dashboard Snapshot", @@ -115,11 +43,26 @@ GET /api/health "cron": "5 4 * * *", "healthStatus": "green", "recentRuns": [ - { "runAt": "2026-01-15T04:05:00.041Z", "state": "success" }, - { "runAt": "2026-01-14T04:05:00.051Z", "state": "success" }, - { "runAt": "2026-01-13T04:05:00.034Z", "state": "success" }, - { "runAt": "2026-01-12T04:05:00.040Z", "state": "success" }, - { "runAt": "2026-01-11T04:05:00.034Z", "state": "success" } + { + "runAt": "2026-01-15T04:05:00.041Z", + "state": "success" + }, + { + "runAt": "2026-01-14T04:05:00.051Z", + "state": "success" + }, + { + "runAt": "2026-01-13T04:05:00.034Z", + "state": "success" + }, + { + "runAt": "2026-01-12T04:05:00.040Z", + "state": "success" + }, + { + "runAt": "2026-01-11T04:05:00.034Z", + "state": "success" + } ] } ], @@ -128,9 +71,9 @@ GET /api/health "id": "4d5fba03-561e-4503-bf4d-c41817133aca", "name": "My Delivery Interface", "type": "webhook", - "healthStatus": "gray", + "healthStatus": "green", "summary24Hours": { - "totalCount": 0, + "totalCount": 11, "errorCount": 0, "errors": [] } @@ -141,12 +84,12 @@ GET /api/health ### Health Status Values -| Status | Meaning | -|--------|---------| -| **green** | All recent runs successful | -| **yellow** | Some recent failures | -| **red** | Most recent runs failed | -| **gray** | No recent activity | +| Status | Meaning | +|------------|----------------------------| +| **green** | All recent runs successful | +| **yellow** | Some recent failures | +| **red** | All recent runs failed | +| **gray** | No recent activity | ## Next Steps diff --git a/docs/administration/spaces.md b/docs/administration/spaces.md index 95cdb55..2b27b8d 100644 --- a/docs/administration/spaces.md +++ b/docs/administration/spaces.md @@ -1,12 +1,13 @@ --- sidebar_position: 2 description: Configure Anaphora Spaces for multi-tenant isolation - separate jobs, reports, and permissions by team or project. -keywords: [multi-tenancy, Spaces, workspace isolation, team separation, RBAC] +keywords: [ multi-tenancy, Spaces, workspace isolation, team separation, RBAC ] --- # Spaces -Spaces provide multi-tenant workspace isolation in Anaphora. They act as "share-nothing" containers that completely separate resources between teams, projects, or tenants. +Spaces provide multi-tenant workspace isolation in Anaphora. They act as "share-nothing" containers that completely +separate resources between teams, projects, or tenants. ![](images/spaces.png) @@ -27,19 +28,16 @@ flowchart TB a1["15 Jobs"] a2["3 Delivery Interfaces"] a3["5 Users"] - a4["AI Provider"] end subgraph spaceB["Space B (Team Beta)"] b1["8 Jobs"] b2["2 Delivery Interfaces"] b3["3 Users"] - b4["AI Provider"] end subgraph spaceC["Space C (Clients)"] c1["50 Jobs"] c2["5 Delivery Interfaces"] c3["10 Users"] - c4["No AI"] end end ``` @@ -48,209 +46,103 @@ flowchart TB Users can belong to multiple Spaces with different roles. ::: -## Share-Nothing Architecture - -Spaces enforce complete isolation: - -| Isolated | Not Shared | -|----------|------------| -| Jobs | Jobs cannot access other Spaces' resources | -| Delivery Interfaces | Each Space configures its own | -| AI Providers | Per-Space AI configuration | -| Reports | Only visible within the Space | -| Run History | Isolated execution logs | -| Templates | Report templates per Space | - ### Copying Between Spaces While resources cannot be shared, they can be copied: -1. Export job configuration from Space A -2. Import into Space B -3. Reconfigure Space-specific settings (delivery, credentials) - -## Creating Spaces - -1. Navigate to **Settings** > **Spaces** -2. Click **Create Space** -3. Enter name and description -4. Configure default settings -5. Save +1. In the jobs list, select the jobs to copy to another Space +2. Click **Copy to Space** +3. Choose target Space +4. If applicable, select to copy associated delivery interfaces -### Space Settings +The same process applies to delivery interfaces. -| Setting | Description | -|---------|-------------| -| **Name** | Unique identifier for the Space | -| **Description** | Purpose/team using this Space | -| **Default Space** | Set as default for new users | -| **Retention Override** | Custom housekeeping rules | - -## User Assignment +## Creating Spaces -Assign users to Spaces with specific roles: +1. Navigate to **Settings** > **System Settings** > **Permissions** +2. Click **Add Space** +3. Enter the name of the Space ### Assignment Process -1. Open Space settings -2. Go to **Members** tab -3. Click **Add Member** -4. Select user or group -5. Assign role (Admin, Editor, Viewer) -6. Save +1. Click **Add Permission** +2. Select user or role +3. Assign permission (Admin, ReadWrite, Readonly) + +:::tip User Roles +Users can have roles assigned to them. These roles can then be assigned to Spaces for easier management. So it is not +necessary to assign each user individually. +::: ### Multi-Space Users -Users can belong to multiple Spaces: +Users can belong to multiple Spaces, by direct assignment or via roles: ``` User: alice@company.com -├── Space: Engineering → Role: Admin -├── Space: Marketing → Role: Viewer -└── Space: DevOps → Role: Editor -``` - -### Group-Based Assignment - -Assign entire groups to Spaces: - -``` -Group: Engineering Team -└── Space: Engineering → Role: Editor - -All members of "Engineering Team" get Editor access to Engineering Space +├── Space: Engineering → Permission: Admin +└── Space: Marketing → Permission: Readonly +Role: DevOps Team +└── Space: DevOps → Permission: ReadWrite ``` ## Switching Spaces -Users with access to multiple Spaces see a Space selector in the navigation. +You can switch between Spaces using the Space selector in the sidebar. -### Current Space Indicator +![space-selector.png](images/space-selector.png) -- Shows active Space name in header -- All operations apply to current Space -- Jobs, reports, settings are Space-specific - -### Quick Switch - -- Click Space selector -- Choose from available Spaces -- View updates immediately +All resources you create or manage will be scoped to the selected Space. ## Use Cases ### Team Separation -| Space | Purpose | -|-------|---------| +| Space | Purpose | +|-------------|--------------------------------------| | Engineering | Technical dashboards, system metrics | -| Marketing | Campaign dashboards, analytics | -| Executive | Summary reports, KPIs | -| DevOps | Infrastructure monitoring, alerts | +| Marketing | Campaign dashboards, analytics | +| Executive | Summary reports, KPIs | +| DevOps | Infrastructure monitoring, alerts | ### Client Isolation (MSP) For managed service providers: -| Space | Client | -|-------|--------| -| Client-Acme | Acme Corp reports | -| Client-Beta | Beta Inc reports | +| Space | Client | +|--------------|-------------------| +| Client-Acme | Acme Corp reports | +| Client-Beta | Beta Inc reports | | Client-Gamma | Gamma Ltd reports | Each client's data is completely isolated. ### Environment Separation -| Space | Environment | -|-------|-------------| -| Production | Live dashboards, real alerts | -| Staging | Test jobs, validation | -| Development | Experimental configurations | - -## Space-Level Settings - -Each Space can override global settings: - -### Retention Policies - -Configure per-Space housekeeping: - -| Setting | Global | Space Override | -|---------|--------|----------------| -| Report retention | 90 days | 365 days (compliance) | -| Run history | 30 days | 7 days (dev Space) | - -### Default Configurations - -Set Space-specific defaults: - -- Default delivery interface -- Default templates -- Default capture settings +| Space | Environment | +|-------------|------------------------------| +| Production | Live dashboards, real alerts | +| Staging | Test jobs, validation | +| Development | Experimental configurations | ## Administration -### Space Admins - -Space Admins can: - -- Manage jobs within their Space -- Configure Space-specific delivery interfaces -- View all reports in the Space -- Manage Space membership - -Space Admins cannot: - -- Access other Spaces (unless assigned) -- Modify global settings -- Create new Spaces - -### System Admins - -System Admins can: +Only system administrators can create and manage Spaces. Space admins can only manage resources within their assigned +Spaces. -- Create and delete Spaces -- Access all Spaces -- Manage global settings -- Override Space configurations +See [Authentication](authentication/index.md) for details on user roles and permissions. ## Best Practices -### Naming Conventions - -Use clear, consistent naming: - -``` -Good: Engineering, Marketing, Client-Acme -Bad: Space1, Test, Temp -``` - ### Permission Principle Assign minimal required permissions: -- Most users: Viewer (report access only) -- Job creators: Editor +- Most users: Space Readonly +- Job creators: Space ReadWrite - Team leads: Space Admin - IT/Operations: System Admin -### Regular Review - -- Audit Space membership quarterly -- Remove inactive users -- Review job configurations -- Check retention policies - -### Documentation - -Document each Space's purpose: - -- What team/project uses it -- What dashboards are captured -- Who receives reports -- Retention requirements - ## Next Steps - [Self Monitoring](./self-monitoring) - Monitor system health diff --git a/docs/advanced-examples/ai-news-collation.md b/docs/advanced-examples/ai-news-collation.md index e534564..8a2ae47 100644 --- a/docs/advanced-examples/ai-news-collation.md +++ b/docs/advanced-examples/ai-news-collation.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Use AI to aggregate, summarize, and deliver curated content from multiple sources with Anaphora. -keywords: [AI summarization, news aggregation, content curation, LLM reports, Anaphora AI] +keywords: [ AI summarization, news aggregation, content curation, LLM reports, Anaphora AI ] --- # AI News Collation @@ -23,50 +23,26 @@ Create a daily digest that collects articles from multiple sources and provides ### 1. Create the Job -Name it: "Daily Industry Digest" +1. Navigate to **Jobs** +2. Click **Create New Job** -### 2. Configure Multi-Source Capture +### 2. Configure Capture -``` -# Source 1: Tech news site -Navigate → https://news.example.com/industry -Capture value → .article-titles → $headlines1 - -# Source 2: Blog aggregator -Navigate → https://blogs.example.com/feed -Capture value → .post-summaries → $headlines2 - -# Source 3: Reddit/HN -Navigate → https://reddit.com/r/industry -Capture value → .post-titles → $headlines3 -``` - -### 3. AI Processing - -Configure AI summarization in the composition phase: -- Combine captured content -- Generate executive summary -- Highlight key trends -- Create actionable insights +1. Enable **Advanced** mode +2. Add multiple **Navigate** actions for each source: + - Ensure that **Take Snapshot** is checked +3. Add **AI** action to process captured content + - Set prompt to: + ``` + Summarize the following articles into an executive summary, highlighting key trends and actionable insights + ``` + - Ensure that all context is included ### 4. Compose the Digest -Structure your report: -1. AI-generated executive summary -2. Top stories by category -3. Trending topics -4. Full article links - -### 5. Deliver - -Send to subscribers via email with a clean, readable format. - -## Tips - -- Filter out duplicates across sources -- Set appropriate content length limits -- Include source attribution +1. Include the AI-generated summary +2. Add other text blocks as needed -## Next Steps +### 5. Configure Delivery -- [Branded Reports](./branded-reports) - Professional report styling +- Add delivery interface and configure recipients diff --git a/docs/advanced-examples/branded-reports.md b/docs/advanced-examples/branded-reports.md deleted file mode 100644 index 152d627..0000000 --- a/docs/advanced-examples/branded-reports.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 4 -description: Create professional branded reports with custom logos, colors, and templates for external stakeholders. -keywords: [branded reports, custom templates, professional PDF, white-label reports, Anaphora branding] ---- - -# Branded Reports - -Create professional, branded reports for external stakeholders. - -## Goal - -Generate polished reports with your company's branding for client delivery. - -## Use Cases - -- Client-facing SLA reports -- Partner performance summaries -- Board presentations -- Compliance documentation - -## Branding Elements - -### Logo and Colors - -Configure your brand assets in Settings: -- Company logo (header/footer) -- Primary and secondary colors -- Font preferences - -### Report Templates - -Create custom templates that include: -- Branded header with logo -- Consistent color scheme -- Professional typography -- Branded footer with contact info - -## Steps - -### 1. Set Up Brand Assets - -1. Navigate to **Settings** > **Branding** -2. Upload your logo -3. Configure color palette -4. Set default fonts - -### 2. Create a Branded Template - -1. Go to **Templates** > **Create New** -2. Design your layout with brand elements -3. Add placeholder sections for dynamic content -4. Save as "Client Report Template" - -### 3. Create the Job - -1. Create a new job for client reporting -2. Configure capture for relevant metrics -3. Select your branded template in Composition -4. Add dynamic fields: client name, date range, etc. - -### 4. Configure Professional Delivery - -- Use PDF format for attachments -- Include personalized email body -- Consider adding cover page - -## Template Variables - -Use variables for personalization: - -| Variable | Description | -|----------|-------------| -| `{{client_name}}` | Client company name | -| `{{report_period}}` | Date range | -| `{{generated_date}}` | Report generation date | - -## Next Steps - -- [Jobs](../jobs/) - Deep dive into job configuration diff --git a/docs/advanced-examples/index.md b/docs/advanced-examples/index.md index c6ec4d7..78f055a 100644 --- a/docs/advanced-examples/index.md +++ b/docs/advanced-examples/index.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Advanced Anaphora examples - multi-source reports, statistical alerts, AI-powered news collation, and branded PDF reports for enterprise use. -keywords: [advanced Kibana reports, multi-source dashboards, statistical alerts, branded reports, AI report generation] +keywords: [ advanced Kibana reports, multi-source dashboards, statistical alerts, branded reports, AI report generation ] --- # Advanced Examples - Enterprise Reporting Scenarios @@ -10,12 +10,11 @@ Complex reporting scenarios demonstrating Anaphora's full capabilities. ## Available Examples -| Example | Description | -|---------|-------------| +| Example | Description | +|------------------------------------------------------------------|-----------------------------------------------------| | [Mixed Sources Report](./advanced-examples/mixed-sources-report) | Combine data from multiple Kibana/Grafana instances | -| [Kibana Statistical Alert](./advanced-examples/kibana-statistical-alert) | Alerts based on statistical analysis | -| [AI News Collation](./advanced-examples/ai-news-collation) | Aggregate and summarize content with AI | -| [Branded Reports](./advanced-examples/branded-reports) | Professional reports with custom branding | +| [Kibana Anomaly Alert](./advanced-examples/kibana-anomaly-alert) | Alerts based on anomaly analysis | +| [AI News Collation](./advanced-examples/ai-news-collation) | Aggregate and summarize content with AI | ## Prerequisites diff --git a/docs/advanced-examples/kibana-anomaly-alert.md b/docs/advanced-examples/kibana-anomaly-alert.md new file mode 100644 index 0000000..5434b5c --- /dev/null +++ b/docs/advanced-examples/kibana-anomaly-alert.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 2 +description: Create sophisticated Kibana alerts based on statistical analysis and trend detection with Anaphora. +keywords: [ statistical alert, trend detection, Kibana analytics, anomaly detection, Anaphora statistics ] +--- + +# Kibana Anomaly Alert + +Create alerts based on deviation from previous data. + +:::tip Kibana Anomaly Detection Template +The **Kibana Anomaly Alert** Template demonstrates this example for the Kibana demo instance. You can use it as a +starting point for your own anomaly detection jobs. +::: + +## Goal + +Alert when metrics deviate significantly from the previous time window. + +## Use Cases + +- Anomaly detection for response times +- Traffic spike alerts +- Resource utilization warnings + +## Steps + +### 1. Create the Job + +1. Navigate to **Jobs** +2. Click **Create New Job** + +### 2. Configure General Settings + +- **Frequency**: Every 15 minutes +- **Max Notify Frequency**: 3 hours + +### 3. Configure Advanced Capture + +1. Enable **Advanced** mode +2. In the preexisting **Navigate**-action: + - select **Kibana** as the connector + - Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` + - Choose authentication method: **ReadonlyREST** and add credentials + - Set time range to 30 minutes to 15 minutes ago +3. Add a **Capture value** action to extract the metric to monitor: + - Set the **variable name** to something like `previous_value` + - Set **capture template** to `Kibana discover hits` + - Set **Variable type** to `Number` +4. Add another **Navigate** action to get the current value: + - select **Kibana** as the connector + - Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` + - Set time range to last 15 minutes +5. Add another **Capture value** action to extract the current metric: + - Set the **variable name** to something like `current_value` + - Set **capture template** to `Kibana discover hits` + - Set **Variable type** to `Number` +6. Add a **Calculate** action to compute the percentage change: + - Set **Variable name** to something like `percent_change` + - Set **Operation** to `round(abs((current_value - previous_value) / previous_value) * 100)` +7. Add a **Conditional block** to check if the percentage change is below the threshold: + - Choose **Variable**: `percent_change` + - Set **Condition operation** to `Lesser than` + - Set **Condition value** to `20` (for 20% change) +8. Inside the conditional block, add a **Break** action to stop execution if the condition is met (i.e., change is below + threshold) + +### 4. Configure Delivery + +- Add delivery interface and configure recipients + +## Next Steps + +- [AI News Collation](./ai-news-collation) - AI-powered content processing diff --git a/docs/advanced-examples/kibana-statistical-alert.md b/docs/advanced-examples/kibana-statistical-alert.md deleted file mode 100644 index 5d7a6f1..0000000 --- a/docs/advanced-examples/kibana-statistical-alert.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -sidebar_position: 2 -description: Create sophisticated Kibana alerts based on statistical analysis and trend detection with Anaphora. -keywords: [statistical alert, trend detection, Kibana analytics, anomaly detection, Anaphora statistics] ---- - -# Kibana Statistical Alert - -Create alerts based on statistical analysis and trend detection. - -## Goal - -Alert when metrics deviate significantly from their normal baseline. - -## Use Cases - -- Anomaly detection for response times -- Traffic spike alerts -- Resource utilization warnings - -## Steps - -### 1. Create the Job - -Name it: "Response Time Anomaly Alert" - -### 2. Configure Advanced Capture - -``` -# Capture current value -Navigate → Kibana dashboard with avg response time -Capture value → [data-test-subj="avgResponseTime"] → $current - -# Capture baseline (you might get this from a saved search) -Navigate → Kibana baseline metrics -Capture value → [data-test-subj="baselineAvg"] → $baseline - -# Calculate deviation -Calculate → (($current - $baseline) / $baseline) * 100 → $deviation - -# Alert if deviation exceeds threshold -Conditional block → $deviation > 50: - ├── Capture snapshot → Full dashboard - └── Continue to delivery -Break -``` - -### 3. Configure Delivery - -- **Channel**: Slack or PagerDuty webhook -- **Message**: `Response time anomaly: {{$current}}ms ({{$deviation}}% above baseline)` - -### 4. Set Throttling - -Set appropriate throttling to avoid alert fatigue during prolonged incidents. - -## Advanced: Rolling Averages - -For more sophisticated analysis, consider: -- Capturing multiple time periods -- Calculating standard deviation -- Using percentile-based thresholds - -## Next Steps - -- [AI News Collation](./ai-news-collation) - AI-powered content processing diff --git a/docs/advanced-examples/mixed-sources-report.md b/docs/advanced-examples/mixed-sources-report.md index cfa37d8..026b3eb 100644 --- a/docs/advanced-examples/mixed-sources-report.md +++ b/docs/advanced-examples/mixed-sources-report.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Combine data from multiple sources like Kibana and Grafana into a single unified report using Anaphora. -keywords: [multi-source report, combined dashboard, Kibana Grafana, unified report, Anaphora advanced] +keywords: [ multi-source report, combined dashboard, Kibana Grafana, unified report, Anaphora advanced ] --- # Mixed Sources Report @@ -11,6 +11,7 @@ Create reports that combine data from multiple sources into a single deliverable ## Goal Generate a weekly executive report combining: + - Kibana: Application metrics dashboard - Grafana: Infrastructure health - Web page: Service status page @@ -25,46 +26,47 @@ Generate a weekly executive report combining: ### 1. Create a New Job -Name it: "Weekly Executive Summary" - -### 2. Configure Advanced Capture - -Build a multi-source workflow: - -``` -# Source 1: Kibana Application Metrics -Navigate → Kibana dashboard URL -Wait for visible → .dashboard-container -Capture snapshot → $appMetrics - -# Source 2: Grafana Infrastructure -Navigate → Grafana dashboard URL -Wait for visible → .react-grid-layout -Capture snapshot → $infraMetrics - -# Source 3: Status Page -Navigate → https://status.example.com -Capture snapshot → $statusPage -``` - -### 3. Configure Composition - -Arrange the three captures in your report template: -1. Header with date and title -2. Application metrics section -3. Infrastructure metrics section -4. Status page summary - -### 4. Deliver - -Send the combined report to your executive team. - -## Tips - -- Use consistent time ranges across sources -- Consider adding summary text between sections -- Test each source individually before combining - -## Next Steps - -- [Kibana Statistical Alert](./kibana-statistical-alert) - Advanced alerting +1. Navigate to **Jobs** +2. Click **Create New Job** + +### 2. Configure General Settings + +- **Frequency**: Weekly on Mondays at 8:00 AM + +### 3. Set Up Advanced Capture + +1. Enable **Advanced** mode to build a multi-capture workflow +2. Edit the preexisting **Navigate**-action: + - Select **Kibana** as the connector + - Enter your Kibana dashboard URL: + ``` + https://kibana.example.com/app/dashboards#/view/application-metrics + ``` + - Choose authentication method: **ReadonlyREST** and add credentials + - Ensure **Take Snapshot** is checked +3. Add a second **Navigate** action: + - Select **Grafana** as the connector + - Enter your Grafana dashboard URL: + ``` + https://grafana.example.com/d/xyz789/infrastructure-health?orgId=1 + ``` + - Set **Authentication** to `Grafana` and add credentials + - Ensure **Take Snapshot** is checked +4. Add a third **Navigate** action: + - Select **Web Page** as the connector + - Enter your service status page URL: + ``` + https://status.example.com + ``` + - No authentication needed + - Ensure **Take Snapshot** is checked + +### 4. Configure Composition + +1. Add all three captured snapshots to the report +2. Arrange them in the desired order +3. Add headers and explanatory text as needed + +### 4. Configure Delivery + +- Add delivery interface and configure recipients diff --git a/docs/basic-examples/conditional-report.md b/docs/basic-examples/conditional-report.md deleted file mode 100644 index 58a3e28..0000000 --- a/docs/basic-examples/conditional-report.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -sidebar_position: 3 -description: Create intelligent alerts that trigger when conditions are met, with AI-powered root cause analysis and detailed PDF reports. -keywords: [Anaphora alerts, conditional alerting, AI root cause analysis, multi-system monitoring, intelligent notifications] ---- - -# Intelligent Alerting - -Create alerts that monitor your systems and notify you only when specific conditions are met — with AI-powered analysis to help identify root causes. - -## The Alerting Concept - -In Anaphora, **an alert is a conditional report**. Instead of sending notifications blindly, Anaphora: - -1. **Captures** data from one or more systems (dashboards, metrics, logs) -2. **Evaluates** conditions based on extracted values -3. **Analyzes** the situation using AI (optional) -4. **Delivers** a detailed PDF with context, not just a notification - -The result: operators receive actionable intelligence, not just "something is wrong." - -## Why PDF Alerts? - -Traditional alerting tools send a message: *"Error rate exceeded 5%"* - -Anaphora sends a **complete situation report**: -- Screenshots of affected dashboards at the moment of the issue -- Extracted metrics and values that triggered the alert -- AI-generated analysis suggesting possible root causes -- Historical context from multiple data sources - -## Use Cases - -| Scenario | What Anaphora Captures | AI Analysis | -|----------|------------------------|-------------| -| Error spike | Error dashboard + log samples | "Error pattern suggests database connection timeout" | -| Performance degradation | APM metrics + infrastructure stats | "CPU spike correlates with deployment at 14:32" | -| Security anomaly | Auth logs + network traffic | "Unusual login pattern from new geographic region" | -| Business threshold | Revenue dashboard + inventory | "Sales drop coincides with payment gateway errors" | - -## Example: Multi-System Alert - -Monitor your stack and get intelligent alerts when things go wrong. - -### 1. Create the Alert Job - -1. Navigate to **Jobs** > **Create New Job** -2. Name it: "Infrastructure Health Alert" -3. Set frequency: Every 5 minutes (`*/5 * * * *`) -4. Set throttling: 1 hour (avoid notification fatigue) - -### 2. Configure Multi-System Capture - -Toggle **Advanced** mode and build a workflow that checks multiple sources: - -``` -Navigate → Grafana infrastructure dashboard -Capture value → CPU usage element → $cpuUsage -Capture value → Error rate element → $errorRate -Capture snapshot → Dashboard overview - -Navigate → Kibana error logs -Capture value → Error count (last 5 min) → $recentErrors -Capture snapshot → Error log view - -Conditional block → $cpuUsage > 80 OR $errorRate > 5 OR $recentErrors > 100: - ├── AI Analysis → "Analyze these metrics and screenshots..." - └── (Continue to Compose/Deliver) -Break → (If all conditions are healthy, stop here) -``` - -### 3. Add AI Analysis - -In the capture workflow, add an **AI Analysis** action: - -``` -Prompt: "Analyze the captured dashboards and metrics: -- CPU: {{$cpuUsage}}% -- Error rate: {{$errorRate}}% -- Recent errors: {{$recentErrors}} - -Based on the visual data and these metrics, identify: -1. The most likely root cause -2. Which systems are affected -3. Recommended immediate actions" -``` - -The AI examines both the **screenshots** and the **extracted values** to provide contextual analysis. - -### 4. Compose the Alert Report - -Design a PDF that gives operators everything they need: - -- **Header**: Alert timestamp and severity -- **AI Summary**: Root cause analysis and recommendations -- **Dashboard Screenshots**: Visual state at time of alert -- **Raw Metrics**: Extracted values that triggered the alert -- **Context**: Links to relevant dashboards for further investigation - -### 5. Configure Delivery - -Send alerts to the right people: -- **Email**: On-call team with PDF attachment -- **Slack**: Alert channel with summary and PDF link -- **Webhook**: Integrate with PagerDuty, Opsgenie, or custom systems - -## How It Works - -```mermaid -flowchart LR - capture["Capture
Multi-system data"] - condition["Evaluate
Check thresholds"] - ai["AI Analysis
Root cause reasoning"] - compose["Compose
Build PDF report"] - deliver["Deliver
Notify operators"] - - capture --> condition - condition -->|"Thresholds exceeded"| ai - condition -->|"All healthy"| stop["Stop
No notification"] - ai --> compose --> deliver -``` - -The **Break** action stops execution when conditions are healthy. No alert fatigue — only actionable notifications. - -## Best Practices - -- **Combine sources**: Capture from multiple systems for complete context -- **Use throttling**: Prevent notification storms during ongoing incidents -- **Include raw data**: AI analysis is helpful, but operators need the numbers too -- **Set clear thresholds**: Start conservative, tune based on real incidents -- **Test the workflow**: Use the Test button to verify conditions trigger correctly - -## Next Steps - -- [Grafana Dashboard Report](./grafana-dashboard-report) - Add Grafana to your monitoring -- [AI Analysis](../advanced-examples/ai-news-collation) - More AI-powered workflows -- [Notification Throttling](../jobs/general#notification-throttling) - Control alert frequency diff --git a/docs/basic-examples/grafana-dashboard-report.md b/docs/basic-examples/grafana-dashboard-report.md index 1a9cd9c..9301e4c 100644 --- a/docs/basic-examples/grafana-dashboard-report.md +++ b/docs/basic-examples/grafana-dashboard-report.md @@ -1,7 +1,7 @@ --- sidebar_position: 4 description: Capture and deliver scheduled Grafana dashboard reports with Anaphora for infrastructure monitoring. -keywords: [Grafana report, dashboard capture, infrastructure monitoring, scheduled report, Anaphora Grafana] +keywords: [ Grafana report, dashboard capture, infrastructure monitoring, scheduled report, Anaphora Grafana ] --- # Grafana Dashboard Report @@ -16,46 +16,36 @@ Send a daily infrastructure health report from Grafana to your ops team. ### 1. Create a New Job -1. Navigate to **Jobs** > **Create New Job** -2. Name it: "Infrastructure Health Report" +1. Navigate to **Jobs** +2. Click **Create New Job** ### 2. Configure General Settings - **Frequency**: Daily at 7:00 AM -- **Description**: "Daily infrastructure metrics from Grafana" ### 3. Set Up Capture -1. Select **Grafana** as the connector (or Generic URL) +1. Select **Grafana** as the connector 2. Enter your Grafana dashboard URL: - ``` - https://grafana.example.com/d/abc123/infrastructure?orgId=1 - ``` -3. Configure authentication (API key or basic auth) -4. Set time range parameters in the URL if needed + ``` + https://grafana.example.com/d/abc123/infrastructure?orgId=1 + ``` +3. Set **Authentication** to `Grafana` and add credentials ### 4. Configure Composition 1. Choose how to arrange captured panels -2. Select PDF or image output format -3. Add custom header with date/time +2. Add texts or headers as needed ### 5. Set Up Delivery 1. Choose delivery interface (Email, Slack, etc.) 2. Configure recipients -3. Set appropriate subject/message ### 6. Test and Save Verify the capture looks correct and save. -## Tips for Grafana - -- Use the `kiosk=tv` URL parameter for cleaner captures -- Set explicit time ranges in URL for consistent reports -- Consider capturing individual panels for more control - ## Next Steps -- [Advanced Examples](../advanced-examples/) - Complex multi-source reports +- [Advanced Examples](../advanced-examples/) - Unlock more complex report scenarios diff --git a/docs/basic-examples/index.md b/docs/basic-examples/index.md index 266bbff..95f8571 100644 --- a/docs/basic-examples/index.md +++ b/docs/basic-examples/index.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Step-by-step Anaphora tutorials for Kibana PDF reports, Grafana dashboard scheduling, and conditional alerts. Practical examples with complete configurations. -keywords: [Kibana PDF report, Grafana scheduled report, dashboard alert, Elasticsearch report, tutorial] +keywords: [ Kibana PDF report, Grafana scheduled report, dashboard alert, Elasticsearch report, tutorial ] --- # Basic Examples - Kibana & Grafana Report Tutorials @@ -10,12 +10,12 @@ Learn Anaphora through practical examples. Each example walks you through creati ## Available Examples -| Example | Description | -|---------|-------------| -| [Kibana Dashboard Report](./basic-examples/kibana-dashboard-report) | Schedule a daily PDF report of your Kibana dashboard | -| [Kibana Alert](./basic-examples/kibana-alert) | Send notifications when conditions are met | -| [Conditional Report](./basic-examples/conditional-report) | Reports that only send when criteria match | -| [Grafana Dashboard Report](./basic-examples/grafana-dashboard-report) | Capture and deliver Grafana dashboards | +| Example | Description | +|-------------------------------------------------------------------------|------------------------------------------------------| +| [Kibana Dashboard Report](./basic-examples/kibana-dashboard-report) | Schedule a daily PDF report of your Kibana dashboard | +| [Kibana Alert](./basic-examples/kibana-alert) | Send notifications when conditions are met | +| [Kibana Conditional Report](./basic-examples/kibana-conditional-report) | Reports that only send when criteria match | +| [Grafana Dashboard Report](./basic-examples/grafana-dashboard-report) | Capture and deliver Grafana dashboards | ## Prerequisites diff --git a/docs/basic-examples/kibana-alert.md b/docs/basic-examples/kibana-alert.md index b098b3b..ba195e3 100644 --- a/docs/basic-examples/kibana-alert.md +++ b/docs/basic-examples/kibana-alert.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Create conditional Kibana alerts with Slack notifications when error thresholds are exceeded using Anaphora. -keywords: [Kibana alert, conditional notification, Slack alert, error threshold, Anaphora alerting] +keywords: [ Kibana alert, conditional notification, Slack alert, error threshold, Anaphora alerting ] --- # Kibana Alert @@ -10,11 +10,12 @@ Create an alert that notifies you when specific conditions are met in your Kiban ## Goal -Send a Slack notification when the error count in your logs exceeds 100 in the last hour. +Send a notification when the error count in your logs exceeds 100 in the last hour. ## Concept In Anaphora, **an alert is a conditional report**. You create alerts by: + 1. Capturing data from Kibana 2. Evaluating conditions 3. Only delivering the report when conditions are met @@ -23,38 +24,41 @@ In Anaphora, **an alert is a conditional report**. You create alerts by: ### 1. Create a New Job -1. Navigate to **Jobs** > **Create New Job** -2. Name it: "Error Rate Alert" +1. Navigate to **Jobs** +2. Click **Create New Job** ### 2. Configure General Settings - **Frequency**: Every 5 minutes (`*/5 * * * *`) -- **Throttling**: 1 hour (avoid notification fatigue) +- **Max notify frequency**: 3 hours (avoid notification fatigue) :::tip Why Throttling? -Even if errors persist every 5 minutes, you'll only get one notification per hour. +Even if errors persist every 5 minutes, you'll only get one notification in 3 hours. ::: -### 3. Set Up Advanced Capture +### 3. Set Up Capture + +1. Select **Kibana** as the connector +2. Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` +3. Choose authentication method: **ReadonlyREST** and add credentials +4. Check **Deliver report only if conditions are met** +5. Set Hits to be greater than `100` -1. Toggle **Advanced** mode on -2. Add actions: +### 4. Compose the Alert Report -``` -Navigate → Kibana Discover (filtered for errors, last 1 hour) -Wait for visible → .euiDataGrid__content -Capture value → [data-test-subj="discoverQueryHits"] → $errorCount -Conditional block → $errorCount > 100: - └── Capture snapshot → Dashboard screenshot -``` +1. Add a text block +2. Edit the text and include `{{kibanaDiscoverHits}}` to show the number of errors +3. Add headers and other text as needed -### 4. Configure Delivery +### 5. Configure Delivery -1. Select **Slack** as delivery interface -2. Choose the alert channel -3. Message: `Alert: {{$errorCount}} errors in the last hour` +1. Select a delivery interface +2. Modify the body: `Alert: {{kibanaDiscoverHits}} errors in the last hour` -### 5. Test and Save +### 6. Test and Save 1. **Test** the job to verify the workflow 2. Check that conditions evaluate correctly @@ -62,8 +66,11 @@ Conditional block → $errorCount > 100: ## Result -You'll receive Slack alerts only when error count exceeds your threshold, with at most one notification per hour. +You'll receive alerts only when error count exceeds your threshold, with at most one notification per hour. ## Next Steps -- [Conditional Report](./conditional-report) - More complex conditions +- [Kibana Conditional Report](./kibana-conditional-report) - Need to also take a dashboard screenshot when the condition is met? See + how to use actions for conditional reports. +- [Kibana Anomaly Alert](../advanced-examples/kibana-anomaly-alert.md) - Need to compare current events to previous + events for anomaly detection? See this example for triggering alerts when events deviate from normal patterns. diff --git a/docs/basic-examples/kibana-conditional-report.md b/docs/basic-examples/kibana-conditional-report.md new file mode 100644 index 0000000..5c2e403 --- /dev/null +++ b/docs/basic-examples/kibana-conditional-report.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 3 +description: Create intelligent alerts that trigger when conditions are met, with AI-powered root cause analysis and detailed PDF reports. +keywords: [ Anaphora alerts, conditional alerting, AI root cause analysis, multi-system monitoring, intelligent notifications ] +--- + +# Kibana Conditional Report + +Create reports that will only be built and delivered when specific conditions are met. + +:::tip Kibana Conditional Snapshot Template +The **Kibana Conditional Snapshot** Template demonstrates this example for the Kibana demo instance. You can +use it as a starting point for your own conditional reporting jobs. +::: + +## Goal + +In this example, we will check the Kibana discover page for error logs. Then we will capture a snapshot of a dashboard. +The report with the captured dashboard will only be delivered if the number of errors exceeds a defined threshold. + +## Steps + +### 1. Create a new job + +1. Navigate to **Jobs** +2. Click **Create New Job** + +### 2. Configure General Settings + +- **Frequency**: Every hour +- **Max Notify Frequency**: 12 hours + +### 3. Set Up Capture + +1. Enable **Advanced** mode to build a conditional workflow +2. In the preexisting **Navigate**-action: + - select **Kibana** as the connector + - Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` + - Choose authentication method: **ReadonlyREST** and add credentials +3. Add a **Capture value** action to extract the number of error logs: + - Set the **variable name** to something like `error_count` + - Set **capture template** to `Kibana discover hits` + - Set **Variable type** to `Number` +4. Add a **Conditional block** to check if the error count is smaller than the threshold: + - Choose **Variable**: `error_count` + - Set **Condition operation** to `Lesser than` + - Set **Condition value** to `100` +5. Inside the conditional block, add a **Break** action to stop execution if the condition is met (i.e., error count is + below threshold) +6. Add another **Navigate** action + - Select **Kibana** as the connector + - Enter your Kibana dashboard URL: + ``` + https://kibana.example.com/app/dashboards#/view/your-dashboard-id + ``` + - Ensure that **Take Snapshot** is checked and set the configuration properly + +### 4. Compose the Report + +1. Add the captured snapshot +2. If desired, add a text block with the `{{error_count}}` variable to show the number of errors +3. Add headers and other text as needed + +### 5. Set Up Delivery + +1. Select **Email** as delivery interface (needs to be configured first in **Delivery Interfaces**) +2. Add recipient email addresses + +## Next Steps + +- [Grafana Dashboard Report](./grafana-dashboard-report) - Add Grafana to your monitoring +- [AI Analysis](../advanced-examples/ai-news-collation) - More AI-powered workflows diff --git a/docs/basic-examples/kibana-dashboard-report.md b/docs/basic-examples/kibana-dashboard-report.md index b7a7611..4cbc17e 100644 --- a/docs/basic-examples/kibana-dashboard-report.md +++ b/docs/basic-examples/kibana-dashboard-report.md @@ -1,13 +1,18 @@ --- sidebar_position: 1 description: Step-by-step tutorial to create a scheduled Kibana dashboard PDF report with email delivery in Anaphora. -keywords: [Kibana report tutorial, scheduled dashboard, PDF email, Anaphora example, dashboard automation] +keywords: [ Kibana report tutorial, scheduled dashboard, PDF email, Anaphora example, dashboard automation ] --- # Kibana Dashboard Report Create a scheduled report that captures your Kibana dashboard and delivers it via email. +:::tip Kibana Dashboard Snapshot Template +The **Kibana Dashboard Snapshot** Template demonstrates this example for the Kibana demo instance. You can use it as a +starting point for your own dashboard reporting jobs. +::: + ## Goal Send a daily PDF report of a Kibana dashboard to your team every morning at 9 AM. @@ -18,38 +23,35 @@ Send a daily PDF report of a Kibana dashboard to your team every morning at 9 AM 1. Navigate to **Jobs** in the sidebar 2. Click **Create New Job** -3. Enter a name: "Daily Dashboard Report" ### 2. Configure General Settings - **Frequency**: Daily at 9:00 AM (or use CRON: `0 9 * * *`) -- **Description**: "Morning dashboard snapshot for the team" ### 3. Set Up Capture 1. Select **Kibana** as the connector 2. Enter your dashboard URL: - ``` - https://your-kibana.example.com/app/dashboards#/view/abc123 - ``` -3. Choose authentication method (Basic or saved profile) + ``` + https://your-kibana.example.com/app/dashboards#/view/abc123 + ``` +3. Choose authentication method: **ReadonlyREST** and add credentials 4. Set time range: "Last 24 hours" ### 4. Configure Composition -1. Select a report template or use default -2. Preview the layout -3. Add header/footer if needed +1. Drag the captured dashboard snapshot into the layout +2. Add additional text blocks if needed +3. Adjust the layout for optimal viewing ### 5. Set Up Delivery -1. Select **Email** as delivery interface +1. Select **Email** as delivery interface (needs to be configured first in **Delivery Interfaces**) 2. Add recipient email addresses -3. Set subject line: `Daily Dashboard Report - {{date}}` ### 6. Test and Save -1. Click **Test** to run the job immediately +1. Use the test to send a sample report to your email 2. Verify the email arrives correctly 3. **Save** the job diff --git a/docs/changelog.md b/docs/changelog.md index de94fdd..74fc1d2 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,7 +1,7 @@ --- sidebar_position: 8 description: Anaphora release notes and changelog. New features, enhancements, bug fixes, and security updates for Kibana/Grafana report automation. -keywords: [Anaphora changelog, release notes, new features, updates, version history] +keywords: [ Anaphora changelog, release notes, new features, updates, version history ] --- # Changelog - Anaphora Release Notes @@ -15,115 +15,18 @@ All notable changes to Anaphora are documented here. - 🧐 **Enhancement** - Improvements to existing features - 🐞 **Fix** - Bug fixes ---- - -## [Unreleased] - -### 🚀 New Feature: Documentation restructure - -
-Complete reorganization of documentation structure - -The documentation has been restructured for better navigation and discoverability: -- New "Basic Examples" and "Advanced Examples" sections -- Dedicated "Jobs" section with detailed component documentation -- Expanded "Delivery Interfaces" with per-interface guides -- New "Administration" section for security and operations -- Added changelog page +## [0.9.0] - 2026-01-15 -
- ---- - -## [1.0.0] - 2024-12-01 - -### 🚀 New Feature: Kibana dashboard capture - -
-Automated screenshot capture from Kibana dashboards - -Anaphora can now capture screenshots from Kibana dashboards, Canvas workpads, and Discover pages. Features include: -- Automatic detection of Kibana page types -- Time range configuration -- Multiple authentication methods -- Full page or viewport capture modes - -
- -### 🚀 New Feature: Grafana support +### 🚀 New Feature: Grafana Connector
Capture and report on Grafana dashboards -Full support for Grafana dashboard capture: -- API key authentication -- Panel-level capture -- Time range parameter support -- Kiosk mode for cleaner captures - -
- -### 🚀 New Feature: Conditional alerts - -
-Send reports only when conditions are met - -Create alerts that only trigger when specific criteria match: -- Extract values from pages into variables -- Perform calculations on captured data -- Conditional execution blocks -- Break action to skip report delivery - -
- -### 🚀 New Feature: Multi-channel delivery - -
-Deliver reports via email, Slack, or webhooks - -Multiple delivery options: -- SMTP email with attachment support -- Mailgun API integration -- Slack workspace integration with rich formatting -- Webhook delivery for custom integrations - -
- -### 🚀 New Feature: Multi-tenant spaces - -
-Isolate jobs and reports by team or project - -Workspace isolation for enterprise deployments: -- Separate jobs and reports per space -- Role-based access control -- Independent retention policies -- User assignment to multiple spaces - -
- -### 🚀 New Feature: Authentication providers - -
-Support for LDAP, SAML, and local authentication - -Enterprise authentication options: -- Local username/password authentication -- LDAP/Active Directory integration -- SAML 2.0 SSO (Okta, Azure AD, OneLogin) -- Role mapping from identity providers - -
- -### 🚀 New Feature: Report templates and branding - -
-Custom branded reports for professional delivery +With the new Grafana connector, Anaphora supports an out-of-the-box experience for capturing Grafana dashboards. +Features include: -Brand your reports: -- Custom logo placement -- Color scheme configuration -- Template variables for personalization -- PDF and image output formats +- Configurable authentication using the Grafana credentials +- Capture entire dashboards with automatic waiting for panels to load +- Capture individual panels for granular reporting
diff --git a/docs/data-retention/index.md b/docs/data-retention/index.md index 7e4b986..37877a0 100644 --- a/docs/data-retention/index.md +++ b/docs/data-retention/index.md @@ -1,12 +1,13 @@ --- sidebar_position: 7 description: Manage Anaphora data retention - configure storage policies for report history, captured data, and audit logs. Automatic housekeeping and cleanup. -keywords: [data retention, report storage, audit logs, retention policy, storage management, housekeeping] +keywords: [ data retention, report storage, audit logs, retention policy, storage management, housekeeping ] --- # Data Retention - Report History & Storage Management -Anaphora stores captured data and generated reports for reference and auditing purposes. This section covers how data is stored, managed, and automatically cleaned up. +Anaphora stores captured data and generated reports for reference and auditing purposes. This section covers how data is +stored, managed, and automatically cleaned up. ## Overview @@ -15,113 +16,10 @@ The Data Retention section provides access to: - **Runs** - Execution history of your jobs, including successful captures, failures, and delivery status - **Reports** - Generated report documents and archives -## Data Types - -| Type | Description | Storage Impact | -|------|-------------|----------------| -| **Captures** | Raw screenshots and extracted data | High | -| **Reports** | Generated PDF and image documents | High | -| **Run History** | Execution logs and status records | Medium | -| **Variables** | Extracted values from capture workflows | Low | -| **Audit Logs** | User actions and system events | Low | - ## Housekeeping & Automatic Cleanup -Anaphora includes automatic housekeeping to manage storage usage over time. - -### Retention Rules - -Configure rules to automatically delete old data: - -```mermaid -flowchart LR - d1["Day 1"] --> d15["Day 15"] --> d30["Day 30"] --> d31["Day 31"] - d31 --> deleted["Deleted"] - - style d31 fill:#ff6b6b - style deleted fill:#ff6b6b -``` - -*Example: Keep only the last 30 days of reports* - -### Configuration Options - -| Setting | Description | Example | -|---------|-------------|---------| -| **Time-based** | Delete data older than X days | Keep last 30 days | -| **Count-based** | Keep only the last X reports | Keep last 100 reports | -| **Size-based** | Delete when storage exceeds limit | Max 10 GB per space | -| **Per-job rules** | Different retention per job type | Critical jobs: 90 days | - -### Housekeeping Schedule - -- Automatic cleanup runs on a configurable schedule -- Default: Daily at midnight (configurable) -- Manual trigger available for immediate cleanup -- Dry-run mode to preview what will be deleted - -## Storage Management - -### Per-Space Isolation - -Each Space maintains its own storage quota and retention policies: - -- Independent retention rules per space -- Storage usage tracking per space -- Alerts when approaching quota limits - -### Storage Metrics - -Monitor storage usage through: - -- Dashboard widgets showing current usage -- Historical trends of storage growth -- Breakdown by data type (captures, reports, logs) -- Projections based on current growth rate - -## Data Lifecycle - -```mermaid -flowchart LR - capture["Capture
Fresh data"] - store["Store
Active access"] - archive["Archive
Aged storage"] - delete["Delete
Expired cleanup"] - - capture --> store --> archive --> delete -``` - -1. **Capture** - New data is captured and stored -2. **Active** - Data is readily available for viewing and export -3. **Archive** - Older data may be compressed or moved to cold storage -4. **Cleanup** - Data exceeding retention policy is permanently deleted - -## Compliance Considerations - -For regulated environments: - -- **Audit trails** - Maintain logs of who accessed what data and when -- **Immutable logs** - System events cannot be modified or deleted -- **Export before delete** - Option to export data before automatic cleanup -- **Legal hold** - Suspend deletion for specific data sets - -## Best Practices - -### Recommended Retention Policies - -| Data Type | Recommended Retention | -|-----------|----------------------| -| Production reports | 90 days | -| Development/test reports | 7-14 days | -| Audit logs | 1 year | -| Run history | 30 days | - -### Storage Optimization - -- Use element-level capture instead of full-page when possible -- Configure appropriate image quality/compression -- Archive important reports externally before cleanup -- Review and adjust retention policies quarterly +Anaphora includes automatic housekeeping to manage storage usage over time. You can configure retention policies for +runs and reports in the job settings. ## Next Steps diff --git a/docs/data-retention/reports.md b/docs/data-retention/reports.md index 1582c3f..cd78305 100644 --- a/docs/data-retention/reports.md +++ b/docs/data-retention/reports.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Access and manage generated reports in Anaphora. Browse report history, configure retention, and download captured data. -keywords: [reports, report storage, report retention, PDF reports, captured data, Anaphora reports] +keywords: [ reports, report storage, report retention, PDF reports, captured data, Anaphora reports ] --- # Reports @@ -12,21 +12,8 @@ The Reports section provides access to all generated report documents and their ## Overview -Reports are the final output of your capture jobs. Each report contains: - -- Captured screenshots -- Extracted data and variables -- Applied templates and formatting -- Delivery timestamps and status - -## Report Types - -| Type | Description | -|------|-------------| -| Screenshot Report | Visual capture of target content | -| Data Report | Extracted values and metrics | -| Composite Report | Combined screenshots and data | -| Template Report | Formatted using custom templates | +Reports are the final output of your capture jobs. A report is a PDF document assembled from captured screenshots, +extracted data, and formatted content. ## Viewing Reports @@ -34,12 +21,9 @@ Access reports through: - **Run history** - View report from specific execution - **Report browser** - Browse all generated reports -- **Search** - Find reports by date, job, or content ## Report Storage -Reports are stored according to your retention policy settings. Configure: - -- **Retention period** - How long to keep reports -- **Storage location** - Local or cloud storage options -- **Archival rules** - Automatic archival of old reports +Most importantly, reports are delivered to configured destinations (email, Slack, S3, webhooks). +However, Anaphora also stores copies of generated reports for reference. +In the job configuration, you can set how long reports are retained. diff --git a/docs/data-retention/runs.md b/docs/data-retention/runs.md index c33c1cd..6cd1239 100644 --- a/docs/data-retention/runs.md +++ b/docs/data-retention/runs.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: View and debug job execution history in Anaphora. Track run statuses, identify failures, and review captured content. -keywords: [job runs, execution history, run status, debugging, job monitoring, Anaphora runs] +keywords: [ job runs, execution history, run status, debugging, job monitoring, Anaphora runs ] --- # Runs @@ -21,28 +21,9 @@ Every time a job executes, a **run** record is created. This allows you to: ## Run Statuses -| Status | Description | -|--------|-------------| -| Success | Job completed and report delivered | -| Partial | Some actions succeeded, others failed | -| Failed | Job execution failed | -| Skipped | Conditions not met, no report sent | - -## Viewing Run Details - -Select any run to view: - -- Execution timestamp -- Job configuration at time of run -- Captured screenshots and data -- Delivery status and logs -- Error messages (if any) - -## Debugging Failed Runs - -When a run fails, check: - -1. **Run logs** - Detailed execution trace -2. **Screenshots** - Visual state at failure point -3. **Network errors** - Connection or timeout issues -4. **Selector changes** - Target page structure may have changed +| Status | Description | +|-----------------|-----------------------------------------------------------------------| +| Success | Job completed and report delivered | +| Delivery issues | The report was created but could not be delivered to all destinations | +| Failed | Job execution failed | +| Skipped | Conditions not met, no report sent | diff --git a/docs/delivery-interfaces/index.md b/docs/delivery-interfaces/index.md index cb0bd8d..b024abb 100644 --- a/docs/delivery-interfaces/index.md +++ b/docs/delivery-interfaces/index.md @@ -1,46 +1,26 @@ --- sidebar_position: 5 description: Configure Anaphora delivery channels - send reports via SMTP email, Mailgun, Slack, webhooks, or S3 archiving. PDF export and multi-channel distribution. -keywords: [email reports, Slack reports, webhook delivery, SMTP configuration, Mailgun integration, S3 archiving, PDF export, report distribution] +keywords: [ email reports, Slack reports, webhook delivery, SMTP configuration, Mailgun integration, S3 archiving, PDF export, report distribution ] --- # Delivery Interfaces - Email, Slack, S3 & Webhook -Delivery Interfaces define how reports reach your recipients. Once a report is generated, Anaphora handles distribution through multiple channels simultaneously. +Delivery Interfaces define how reports reach your recipients. Once a report is generated, Anaphora handles distribution +through multiple channels simultaneously. ## Available Interfaces -| Interface | Description | Best For | -|-----------|-------------|----------| -| [SMTP](/delivery-interfaces/smtp) | Direct email via SMTP server | Corporate email systems | -| [Mailgun](/delivery-interfaces/mailgun) | Email via Mailgun API | High-volume delivery | -| [Slack](/delivery-interfaces/slack) | Slack workspace integration | Team notifications | -| [S3](/delivery-interfaces/s3) | S3-compatible object storage | Archiving & compliance | -| [WebHook](/delivery-interfaces/webhook) | Custom HTTP endpoints | Integrations & automation | - -## Output Formats - -Reports can be delivered in multiple formats: - -| Format | Description | Use Case | -|--------|-------------|----------| -| **PDF** | Portable document format | Formal reports, archiving, printing | -| **PNG/JPEG** | Image formats | Quick previews, Slack thumbnails | -| **HTML** | Web format | Interactive viewing, email body | -| **Raw data** | JSON payload | Webhook integrations, further processing | - -## PDF Export - -Generate professional PDF reports directly from Anaphora: - -- **View in browser** - Preview reports before delivery -- **Download** - Manual PDF export from the Reports section -- **Email attachment** - Automatically attach PDFs to email delivery -- **Custom styling** - Branded headers, footers, and page layouts +| Interface | Description | Best For | +|-----------------------------------------|------------------------------|---------------------------| +| [SMTP](/delivery-interfaces/smtp) | Direct email via SMTP server | Corporate email systems | +| [Mailgun](/delivery-interfaces/mailgun) | Email via Mailgun API | High-volume delivery | +| [S3](/delivery-interfaces/s3) | S3-compatible object storage | Archiving & compliance | +| [WebHook](/delivery-interfaces/webhook) | Custom HTTP endpoints | Integrations & automation | ## Configuration -1. Navigate to **Settings** > **Delivery Interfaces** +1. Navigate to **Delivery Interfaces** 2. Click **Add Interface** 3. Select type and configure credentials 4. Test the connection @@ -51,39 +31,7 @@ Generate professional PDF reports directly from Anaphora: Once configured, interfaces appear in the job's **Delivery** tab: - Select one or multiple delivery channels -- Configure per-channel settings (recipients, subject lines, etc.) -- Set delivery conditions (always, on success, on failure) - -## Multiple Interfaces - -You can configure multiple interfaces of the same type: - -| Scenario | Configuration | -|----------|---------------| -| **Different teams** | Separate Slack channels per team | -| **Backup delivery** | Primary SMTP + fallback Mailgun | -| **Regional separation** | Different email servers per region | -| **Integration variety** | Multiple webhooks for different systems | - -## Delivery Flow - -```mermaid -flowchart LR - report["Report Generated"] - - subgraph interfaces["Delivery Interfaces"] - email["Email"] - slack["Slack"] - s3["S3"] - webhook["Webhook"] - end - - report --> interfaces - email --> recipients["Recipients"] - slack --> channels["Channels"] - s3 --> bucket["S3 Bucket"] - webhook --> endpoints["Endpoints"] -``` +- Configure per-channel settings (recipients, notification body, etc.) ## Next Steps diff --git a/docs/delivery-interfaces/mailgun.md b/docs/delivery-interfaces/mailgun.md index db47b06..908efc6 100644 --- a/docs/delivery-interfaces/mailgun.md +++ b/docs/delivery-interfaces/mailgun.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Configure Mailgun API integration for reliable email delivery with built-in analytics and better deliverability. -keywords: [Mailgun integration, email API, transactional email, Anaphora Mailgun, email delivery] +keywords: [ Mailgun integration, email API, transactional email, Anaphora Mailgun, email delivery ] --- # Mailgun @@ -14,18 +14,17 @@ Send reports via the Mailgun email API. - No SMTP server to manage - Better deliverability tracking -- Built-in analytics +- Easy setup - Higher sending limits ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| API Key | Mailgun API key | Yes | -| Domain | Your Mailgun domain | Yes | -| From Address | Sender email | Yes | -| Region | US or EU | Yes | +| Field | Description | Required | +|-----------------|-------------------------------------------------------------------------|----------| +| Name | Interface identifier | Yes | +| Sender email | Use your MailGun domain with any name e.g. myname@my-mailgun-domain.com | Yes | +| Sender name | Use any name that should be displayed as sender | No | +| Mailgun API key | API authentication | Yes | ## Setup Steps @@ -34,20 +33,12 @@ Send reports via the Mailgun email API. 1. Log in to Mailgun 2. Navigate to **Settings** > **API Keys** 3. Copy your Private API Key -4. Note your sending domain - -### 2. Configure in Anaphora - -1. Go to **Settings** > **Delivery Interfaces** -2. Add new **Mailgun** interface -3. Enter API key and domain -4. Select region (US or EU) -5. Set from address -6. Test and save +4. Note your Mailgun sender domain (to use in sender email) ## Domain Verification Ensure your Mailgun domain is verified for best deliverability: + - Add DNS records as instructed by Mailgun - Verify SPF and DKIM are configured diff --git a/docs/delivery-interfaces/s3.md b/docs/delivery-interfaces/s3.md index 0986330..ad2c4ad 100644 --- a/docs/delivery-interfaces/s3.md +++ b/docs/delivery-interfaces/s3.md @@ -1,34 +1,34 @@ --- sidebar_position: 5 description: Archive reports to S3 object storage - AWS S3, MinIO, and S3-compatible storage for compliance and historical records. -keywords: [S3 archiving, AWS S3, MinIO, object storage, report archive, compliance storage] +keywords: [ S3 archiving, AWS S3, MinIO, object storage, report archive, compliance storage ] --- # S3 Object Storage + Archive reports to S3-compatible object storage for long-term retention, compliance, and historical reference. ![S3 Object Storage delivery interface configuration showing access key, secret key, region, bucket name, and custom endpoint fields](images/s3.png) ## Use Cases -| Scenario | Benefit | -|----------|---------| -| **Compliance archiving** | Immutable records for audit requirements | +| Scenario | Benefit | +|--------------------------|------------------------------------------------| +| **Compliance archiving** | Immutable records for audit requirements | | **Historical reference** | "What did this dashboard look like on date X?" | -| **Long-term retention** | Store beyond housekeeping limits | -| **Cross-system access** | Other tools can retrieve archived reports | +| **Long-term retention** | Store beyond housekeeping limits | +| **Cross-system access** | Other tools can retrieve archived reports | ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| **Name** | Interface identifier | Yes | -| **Type** | S3 Object Storage | Yes | -| **Access key ID** | AWS access key or S3-compatible credentials | Yes | -| **Secret access key** | AWS secret key (stored encrypted) | Yes | -| **Region** | AWS region (e.g., `eu-west-1`) | Yes | -| **Bucket name** | Target S3 bucket | Yes | -| **Custom endpoint** | For S3-compatible storage (MinIO, etc.) | No | +| Field | Description | Required | +|-----------------------|---------------------------------------------|----------| +| **Name** | Interface identifier | Yes | +| **Access key ID** | AWS access key or S3-compatible credentials | Yes | +| **Secret access key** | AWS secret key (stored encrypted) | Yes | +| **Region** | AWS region (e.g., `eu-west-1`) | Yes | +| **Bucket name** | Target S3 bucket | Yes | +| **Custom endpoint** | For S3-compatible storage (MinIO, etc.) | No | ## Provider Configurations @@ -72,38 +72,6 @@ Bucket name: your-bucket Custom endpoint: https://s3.us-west-002.backblazeb2.com ``` -## Path Organization - -Reports are stored with a configurable path structure. Configure the path prefix in the job's Delivery settings: - -``` -s3://my-reports-bucket/ -├── anaphora/ -│ ├── daily-dashboards/ -│ │ ├── 2025/ -│ │ │ ├── 01/ -│ │ │ │ ├── 2025-01-15-dashboard.pdf -│ │ │ │ └── 2025-01-16-dashboard.pdf -│ ├── compliance-reports/ -│ │ └── ... -│ └── alerts/ -│ └── ... -``` - -### Path Variables - -Use variables in the path prefix for automatic organization: - -| Variable | Description | Example | -|----------|-------------|---------| -| `{{year}}` | 4-digit year | `2025` | -| `{{month}}` | 2-digit month | `01` | -| `{{day}}` | 2-digit day | `15` | -| `{{job_name}}` | Job identifier | `daily-dashboard` | -| `{{date}}` | Full date | `2025-01-15` | - -**Example path prefix:** `anaphora/{{job_name}}/{{year}}/{{month}}/` - ## IAM Permissions For AWS S3, the IAM user/role needs these permissions: @@ -132,55 +100,21 @@ For AWS S3, the IAM user/role needs these permissions: For write-only archiving, you can remove `s3:GetObject` permission. ::: -## Lifecycle Policies - -Configure S3 lifecycle policies for automatic management: - -| Policy | Description | -|--------|-------------| -| **Transition to Glacier** | Move old reports to cheaper storage | -| **Expiration** | Auto-delete after retention period | -| **Versioning** | Keep multiple versions for compliance | - -### Example Lifecycle Rule (AWS) - -```json -{ - "Rules": [ - { - "ID": "ArchiveOldReports", - "Status": "Enabled", - "Filter": { "Prefix": "anaphora/" }, - "Transitions": [ - { - "Days": 90, - "StorageClass": "GLACIER" - } - ], - "Expiration": { - "Days": 365 - } - } - ] -} -``` - ## Testing 1. Configure the S3 interface with your credentials 2. Click **Test** 3. Verify a test file appears in your bucket -4. Check the file path matches your expectations ## Troubleshooting -| Issue | Solution | -|-------|----------| -| Access Denied | Verify IAM permissions, check bucket policy | -| Invalid credentials | Double-check access key and secret | -| Bucket not found | Verify bucket name and region match | -| Connection timeout | Check custom endpoint URL, verify network access | -| SSL certificate error | For self-signed certs, configure trust settings | +| Issue | Solution | +|-----------------------|--------------------------------------------------| +| Access Denied | Verify IAM permissions, check bucket policy | +| Invalid credentials | Double-check access key and secret | +| Bucket not found | Verify bucket name and region match | +| Connection timeout | Check custom endpoint URL, verify network access | +| SSL certificate error | For self-signed certs, configure trust settings | ## Best Practices @@ -189,18 +123,4 @@ Configure S3 lifecycle policies for automatic management: - Use dedicated IAM credentials with minimal permissions - Enable bucket versioning for compliance requirements - Consider enabling server-side encryption (SSE-S3 or SSE-KMS) -- Restrict bucket access with bucket policies - -### Organization - -- Use consistent path prefixes across jobs -- Include date components for easy browsing -- Separate compliance reports from operational reports -- Document your bucket structure - -### Cost Management - -- Configure lifecycle policies to transition old data to Glacier -- Set expiration for non-critical reports -- Monitor bucket size and request costs -- Consider S3 Intelligent-Tiering for variable access patterns +- Restrict bucket access with bucket policies \ No newline at end of file diff --git a/docs/delivery-interfaces/slack.md b/docs/delivery-interfaces/slack.md index 6ebe680..4b00de9 100644 --- a/docs/delivery-interfaces/slack.md +++ b/docs/delivery-interfaces/slack.md @@ -1,61 +1,30 @@ --- sidebar_position: 3 description: Configure Slack webhook integration to deliver Anaphora reports directly to Slack channels with rich formatting. -keywords: [Slack integration, webhook delivery, Slack notifications, report delivery, Anaphora Slack] +keywords: [ Slack integration, webhook delivery, Slack notifications, report delivery, Anaphora Slack ] --- # Slack -Deliver reports directly to Slack channels. - -## Configuration - -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| Webhook URL | Slack Incoming Webhook | Yes | -| Default Channel | Fallback channel | No | +Deliver reports directly to Slack channels. Use the webhook delivery interface to send Slack messages. ## Setup Steps -### 1. Create Slack App - -1. Go to [api.slack.com/apps](https://api.slack.com/apps) -2. Click **Create New App** -3. Choose **From scratch** -4. Name it "Anaphora" and select workspace +### 1. Create Slack Webhook -### 2. Enable Incoming Webhooks +1. Go to [Slack Docs](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) +2. Follow the instructions to create an **Incoming Webhook** -1. In app settings, go to **Incoming Webhooks** -2. Toggle **Activate Incoming Webhooks** on -3. Click **Add New Webhook to Workspace** -4. Select the default channel -5. Copy the Webhook URL +### 2. Configure in Anaphora -### 3. Configure in Anaphora - -1. Go to **Settings** > **Delivery Interfaces** -2. Add new **Slack** interface +1. Go to **Delivery Interfaces** +2. Add new **Webhook** interface 3. Paste the Webhook URL -4. Test and save - -## Message Formatting - -Reports sent to Slack include: -- Report title as header -- Thumbnail preview (if image) -- Download link for full PDF -- Key metrics (if extracted) - -## Multiple Channels - -Create separate interfaces for different channels, or override the channel per-job. - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Webhook invalid | Regenerate webhook URL | -| Channel not found | Verify channel exists and bot has access | -| Message too large | Reduce captured content size | +4. Set the method to **POST** and body type to **JSON** +5. Add the JSON body: + ```json + { + "text": "Hello, world." + } + ``` +6. Test and save diff --git a/docs/delivery-interfaces/smtp.md b/docs/delivery-interfaces/smtp.md index 2cddaf2..72ac868 100644 --- a/docs/delivery-interfaces/smtp.md +++ b/docs/delivery-interfaces/smtp.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Configure SMTP email delivery for Anaphora reports. Supports SSL, STARTTLS, and common providers like Gmail and Office 365. -keywords: [SMTP configuration, email delivery, SSL email, Gmail SMTP, Office 365 SMTP, Anaphora email] +keywords: [ SMTP configuration, email delivery, SSL email, Gmail SMTP, Office 365 SMTP, Anaphora email ] --- # SMTP @@ -12,15 +12,15 @@ Send reports via your own SMTP email server. Supports SSL, STARTLS, plain ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| Host | SMTP server hostname | Yes | -| Port | SMTP port (25, 465, 587) | Yes | -| Username | SMTP authentication user | Usually | -| Password | SMTP authentication password | Usually | -| From Address | Sender email address | Yes | -| TLS/SSL | Encryption mode | Recommended | +| Field | Description | Required | +|--------------|------------------------------|-------------| +| Name | Interface identifier | Yes | +| Host | SMTP server hostname | Yes | +| Port | SMTP port (25, 465, 587) | Yes | +| Username | SMTP authentication user | Usually | +| Password | SMTP authentication password | Usually | +| From Address | Sender email address | Yes | +| TLS/SSL | Encryption mode | Recommended | ## Common Configurations @@ -61,8 +61,8 @@ TLS: STARTTLS ## Troubleshooting -| Issue | Solution | -|-------|----------| -| Connection refused | Check firewall, verify port | +| Issue | Solution | +|-----------------------|-----------------------------------------| +| Connection refused | Check firewall, verify port | | Authentication failed | Verify credentials, check app passwords | -| TLS error | Try different TLS mode | +| TLS error | Try different TLS mode | diff --git a/docs/delivery-interfaces/webhook.md b/docs/delivery-interfaces/webhook.md index f4e6fdb..28a2b28 100644 --- a/docs/delivery-interfaces/webhook.md +++ b/docs/delivery-interfaces/webhook.md @@ -1,7 +1,7 @@ --- sidebar_position: 4 description: Configure webhook delivery to send Anaphora reports to custom HTTP endpoints. Integrate with any system via JSON payloads. -keywords: [webhook integration, HTTP delivery, API integration, custom notifications, automation, Anaphora webhook] +keywords: [ webhook integration, HTTP delivery, API integration, custom notifications, automation, Anaphora webhook ] --- # WebHook @@ -19,67 +19,53 @@ Send reports to custom HTTP endpoints for integration with any system. ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| URL | Endpoint URL | Yes | -| Method | HTTP method (POST/PUT) | Yes | -| Headers | Custom headers | No | -| Authentication | Basic/Bearer/None | No | +| Field | Description | Required | +|-----------|-------------------------|----------| +| Name | Interface identifier | Yes | +| URL | Endpoint URL | Yes | +| Method | HTTP method (POST/PUT) | Yes | +| Headers | Custom headers | No | +| Body type | JSON, form-data | Yes | +| JSON Body | Custom payload template | No | +| Form Data | Key-value pairs | No | ## Payload Format -Anaphora sends a JSON payload: +### JSON Template + +Define a JSON structure that works with your endpoint. Use the ```$MESSAGE``` variable as placeholder for the report +content. This variable will be replaced with the custom text that you define in the job's delivery settings. + +Example: ```json { - "job_name": "Daily Report", - "job_id": "abc123", - "timestamp": "2026-01-15T09:00:00Z", - "status": "success", - "report_url": "https://anaphora.example.com/reports/xyz", - "variables": { - "error_count": 42, - "alert_triggered": true - }, - "attachments": [ - { - "type": "pdf", - "url": "https://anaphora.example.com/files/report.pdf" - } - ] + "title": "Anaphora Report", + "content": "$MESSAGE" } ``` -## Custom Headers +### Form Data -Add headers for authentication or routing: +Send key-value pairs as form data. Use the ```$MESSAGE``` variable for the report content. + +Example: ``` -Authorization: Bearer your-token -X-Custom-Header: value -Content-Type: application/json +report_title=Anaphora Report +report_content=$MESSAGE ``` -## Authentication Options +### JSON in Job Delivery -| Type | Configuration | -|------|---------------| -| None | No authentication | -| Basic | Username and password | -| Bearer | Token in Authorization header | -| Custom | Via custom headers | +In this case the entire body is defined in the job's delivery settings. -## Testing - -1. Use a tool like [webhook.site](https://webhook.site) for testing -2. Configure the test URL in Anaphora -3. Send a test payload -4. Verify the payload structure meets your needs +## Custom Headers -## Error Handling +Add headers for authentication or routing: -Anaphora retries failed webhook deliveries: -- 3 retry attempts -- Exponential backoff -- Failures logged in job history +``` +Authorization: Bearer your-token +X-Custom-Header: value +Content-Type: application/json +``` diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index a35ba65..569c2b8 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -1,53 +1,25 @@ --- sidebar_position: 2 description: Configure Anaphora with environment variables for production deployments. PUBLIC_URL, admin credentials, and license setup. -keywords: [Anaphora configuration, environment variables, PUBLIC_URL, setup guide, production deployment] +keywords: [ Anaphora configuration, environment variables, PUBLIC_URL, setup guide, production deployment ] --- # Configuration Guide -Configure Anaphora for your environment and requirements. - -## Environment Variables - -Anaphora is configured via environment variables: - -| Variable | Description | Required | -|----------|-------------|----------| -| `PUBLIC_URL` | External URL where Anaphora is accessible | Yes (production) | -| `ADMIN_USERNAME` | Initial admin username | No (default: `admin`) | -| `ADMIN_PASSWORD` | Initial admin password | No (prompted on first login) | -| `ACTIVATION_KEY` | PRO/Enterprise activation key | No | -| `ANAPHORA_DATA_DIR` | Data storage path | No (default: `/data`) | - -### PUBLIC_URL - -The `PUBLIC_URL` environment variable defines the external URL where Anaphora is accessible. This is **required for production deployments** and used for: - -- SSO callback URLs (SAML, OIDC) -- Links in email notifications -- Webhook response URLs - -```bash -# Example: Production deployment -PUBLIC_URL=https://anaphora.company.com - -# Example: Local development (optional) -PUBLIC_URL=http://localhost:3000 -``` - -:::warning Required for SSO -If you're using SAML or OIDC authentication, `PUBLIC_URL` must be set correctly. The callback URLs registered with your identity provider must match this value. -::: +After installing Anaphora and setting it up with Environment variables, you can further configure it in the admin UI. ## Initial Setup On first launch: 1. Navigate to `PUBLIC_URL` in your browser -2. Log in with admin credentials (set via environment variables or prompted) -3. Configure your license if using PRO/Enterprise features -4. Create your first job +2. Create the initial admin user (if not set via env vars) +3. Log in with your admin credentials +4. Go to **Settings** → **System** to review and adjust global settings +5. Configure your license if using PRO/Enterprise features +6. Create your first job + + ## Next Steps diff --git a/docs/getting-started/features.md b/docs/getting-started/features.md index c119cc5..842a6cf 100644 --- a/docs/getting-started/features.md +++ b/docs/getting-started/features.md @@ -1,12 +1,13 @@ --- sidebar_position: 3 description: Compare Anaphora Free, PRO, and Enterprise editions. See what's included in each tier and choose the right plan for your reporting needs. -keywords: [Anaphora features, free edition, pro license, enterprise edition, activation key, feature comparison, pricing tiers] +keywords: [ Anaphora features, free edition, pro license, enterprise edition, activation key, feature comparison, pricing tiers ] --- # Features & Editions -Choose the edition that fits your needs. All editions include the **full reporting engine** — higher tiers unlock team features and integrations. +Choose the edition that fits your needs. All editions include the **full reporting engine** — higher tiers unlock team +features and integrations. :::info 🚀 Ready to try PRO or Enterprise? **[Get a free trial key →](https://portal.anaphora.it)** — No credit card required. Instant activation. @@ -17,13 +18,16 @@ Choose the edition that fits your needs. All editions include the **full reporti **Perfect for evaluation and personal projects** :::tip What you get + - ✅ Up to **2 scheduled jobs** - ✅ Kibana, Grafana, and generic web capture - ✅ PDF report composer with custom layouts -- ✅ Email (SMTP), Mailgun, Slack, and Webhook delivery +- ✅ Email (SMTP) delivery - ✅ Notification throttling and retry policies - ✅ Local user authentication -::: +- ✅ **Self-Monitoring API** — health endpoints for external systems +- ✅ **AI Analysis** — LLM-powered summaries and anomaly detection + ::: **Best for:** Trying Anaphora, personal dashboards, small-scale reporting @@ -34,11 +38,12 @@ Choose the edition that fits your needs. All editions include the **full reporti **For production teams who need unlimited jobs and AI** :::tip Everything in Free, plus + - ✅ **Unlimited jobs** — no restrictions +- ✅ **Additional Delivery** - Mailgun, Slack, Webhook, and S3 - ✅ **Spaces** — organize jobs into isolated workspaces -- ✅ **AI Analysis** — LLM-powered summaries and anomaly detection - ✅ **Priority support** — faster response times -::: + ::: **Best for:** Production workloads, growing teams, AI-enhanced reports @@ -49,11 +54,12 @@ Choose the edition that fits your needs. All editions include the **full reporti **For organizations requiring SSO and compliance** :::tip Everything in PRO, plus + - ✅ **LDAP / Active Directory** — enterprise directory auth - ✅ **SAML SSO** — Okta, Azure AD, OneLogin, etc. - ✅ **OpenID Connect** — Google, Auth0, Keycloak, etc. -- ✅ **S3 Archiving** — compliance-ready report storage -- ✅ **Self-Monitoring API** — health endpoints for external systems +- ✅ **Branding** — Customization of login screen + ::: **Best for:** Corporate SSO requirements, compliance, large-scale deployments @@ -62,36 +68,41 @@ Choose the edition that fits your needs. All editions include the **full reporti ## Feature Comparison -| Feature | 🆓 Free | ⭐ PRO | 🏢 Enterprise | -|---------|:-------:|:------:|:-------------:| -| **Jobs** | 2 | ∞ Unlimited | ∞ Unlimited | -| | | | | -| **Capture** | | | | -| Kibana Connector | ✅ | ✅ | ✅ | -| Grafana Connector | ✅ | ✅ | ✅ | -| Generic Web Capture | ✅ | ✅ | ✅ | -| PDF Composer | ✅ | ✅ | ✅ | -| | | | | -| **Delivery** | | | | -| Email (SMTP) | ✅ | ✅ | ✅ | -| Mailgun | ✅ | ✅ | ✅ | -| Slack | ✅ | ✅ | ✅ | -| Webhook | ✅ | ✅ | ✅ | -| S3 Archiving | ❌ | ❌ | ✅ | -| | | | | -| **Team & Organization** | | | | -| Spaces (Multi-tenancy) | ❌ | ✅ | ✅ | -| AI Analysis | ❌ | ✅ | ✅ | -| | | | | -| **Authentication** | | | | -| Local Users | ✅ | ✅ | ✅ | -| LDAP / Active Directory | ❌ | ❌ | ✅ | -| SAML SSO | ❌ | ❌ | ✅ | -| OpenID Connect | ❌ | ❌ | ✅ | -| | | | | -| **Operations** | | | | -| Self-Monitoring API | ❌ | ❌ | ✅ | -| Priority Support | ❌ | ✅ | ✅ | +| Feature | 🆓 Free | ⭐ PRO | 🏢 Enterprise | +|-------------------------|:-------:|:-----------:|:-------------:| +| **Jobs** | 2 | ∞ Unlimited | ∞ Unlimited | +| **Delivery Interfaces** | 2 | ∞ Unlimited | ∞ Unlimited | +| | | | | +| **Capture** | | | | +| Capture Actions | 3 | ∞ Unlimited | ∞ Unlimited | +| Kibana Connector | ✅ | ✅ | ✅ | +| Grafana Connector | ✅ | ✅ | ✅ | +| Generic Web Capture | ✅ | ✅ | ✅ | +| PDF Composer | ✅ | ✅ | ✅ | +| | | | | +| **Delivery** | | | | +| Email (SMTP) | ✅ | ✅ | ✅ | +| Mailgun | ❌ | ✅ | ✅ | +| Slack | ❌ | ✅ | ✅ | +| Webhook | ❌ | ✅ | ✅ | +| S3 Archiving | ❌ | ✅ | ✅ | +| | | | | +| **Team & Organization** | | | | +| AI Analysis | ✅ | ✅ | ✅ | +| Job Templates | ✅ | ✅ | ✅ | +| Advanced Job Templates | ❌ | ✅ | ✅ | +| Spaces (Multi-tenancy) | ❌ | ✅ | ✅ | +| Branding | ❌ | ❌ | ✅ | +| | | | | +| **Authentication** | | | | +| Local Users | ✅ | ✅ | ✅ | +| LDAP / Active Directory | ❌ | ❌ | ✅ | +| SAML SSO | ❌ | ❌ | ✅ | +| OpenID Connect | ❌ | ❌ | ✅ | +| | | | | +| **Operations** | | | | +| Self-Monitoring API | ✅ | ✅ | ✅ | +| Priority Support | ❌ | ✅ | ✅ | ## Activation Keys @@ -131,7 +142,7 @@ docker run -p 3000:3000 \ - Instant delivery — no waiting - Full access to all features - No credit card required -::: + ::: ## Need Help? diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 6ca9e43..4f4b713 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Install Anaphora with Docker or Docker Compose. Quick setup guide for automated Kibana and Grafana report generation. -keywords: [Anaphora installation, Docker setup, Kibana reporting tool, Grafana reporting tool, automated reports installation] +keywords: [ Anaphora installation, Docker setup, Kibana reporting tool, Grafana reporting tool, automated reports installation ] --- # Installation Guide @@ -11,7 +11,6 @@ Get Anaphora up and running in your environment. ## Requirements - Docker and Docker Compose (recommended) -- Or: Java 17+ runtime environment - Network access to your Kibana/Grafana instances ## Quick Start with Docker @@ -21,23 +20,27 @@ The fastest way to get started is using Docker: ```bash docker run -p 3000:3000 \ -e PUBLIC_URL=http://localhost:3000 \ - -e ADMIN_USERNAME=admin \ - -e ADMIN_PASSWORD=admin \ - -d beshu-tech/anaphora + -e DB_ENCRYPTION_KEY=your-encryption-key \ + -d beshultd/anaphora ``` Then open [http://localhost:3000](http://localhost:3000) in your browser and log in with `admin` / `admin`. ### Environment Variables -| Variable | Description | Example | -|----------|-------------|---------| -| `PUBLIC_URL` | External URL where Anaphora is accessible | `http://anaphora.example.com:3000` | -| `ADMIN_USERNAME` | Initial admin username | `admin` | -| `ADMIN_PASSWORD` | Initial admin password | `your-secure-password` | +| Variable | Description | Required | Example | +|---------------------|-------------------------------------------------|-------------|------------------------------------| +| `PUBLIC_URL` | External URL where Anaphora is accessible | Yes | `http://anaphora.example.com:3000` | +| `DB_ENCRYPTION_KEY` | Key used to encrypt the DB. | Recommended | `your-encryption-key` | +| `ADMIN_USERNAME` | Initial admin username | No | `admin` | +| `ADMIN_PASSWORD` | Initial admin password | No | `your-secure-password` | +| `ACTIVATION_KEY` | License / activation key for Anaphora | No | `xxxx-xxxx-xxxx-xxxx` | +| `DEBUG` | Enable debug logging | No | `false` | +| `WORKER_COUNT` | Number of concurrent Puppeteer worker instances | No | `2` | :::tip Production Deployment -For production, use a strong password and set `PUBLIC_URL` to your actual external URL (this is used for callback URLs in SSO configurations). +For production, use a strong `DB_ENCRYPTION_KEY` and set `PUBLIC_URL` to your actual external URL (this is used for +callback URLs in SSO configurations). ::: ### Docker Compose @@ -48,23 +51,29 @@ For production deployments, use Docker Compose with persistent storage: version: '3.8' services: anaphora: - image: beshu-tech/anaphora + image: beshultd/anaphora ports: - "3000:3000" volumes: - - anaphora-data:/data + - anaphora-storage:/usr/src/app/storage + - anaphora-content:/usr/src/app/content environment: - PUBLIC_URL=https://anaphora.example.com + - DB_ENCRYPTION_KEY=${DB_ENCRYPTION_KEY} - ADMIN_USERNAME=admin - ADMIN_PASSWORD=${ADMIN_PASSWORD} - ACTIVATION_KEY=${ACTIVATION_KEY} + - DEBUG=false + - WORKER_COUNT=2 volumes: - anaphora-data: + anaphora-storage: + anaphora-content: ``` :::tip 🎁 Get a Free Trial Key -The `ACTIVATION_KEY` unlocks PRO or Enterprise features. **[Request your free trial key →](https://portal.anaphora.it)** — instant activation, no credit card required. +The `ACTIVATION_KEY` unlocks PRO or Enterprise features. +**[Request your free trial key →](https://portal.anaphora.it)** — instant activation, no credit card required. ::: ## Need Help? diff --git a/docs/jobs/capture.md b/docs/jobs/capture.md index 549c191..c0bb366 100644 --- a/docs/jobs/capture.md +++ b/docs/jobs/capture.md @@ -1,29 +1,31 @@ --- sidebar_position: 2 description: Configure Anaphora capture settings - Kibana, Grafana, and generic web connectors with authentication and advanced multi-step workflows. -keywords: [Kibana capture, Grafana capture, headless browser, web scraping, dashboard capture, authentication] +keywords: [ Kibana capture, Grafana capture, headless browser, web scraping, dashboard capture, authentication ] --- # Capture Configuration -The Capture tab defines what data to collect and how. Anaphora's headless Chrome-based connector can navigate, authenticate, and capture any web application. +The Capture tab defines what data to collect and how. Anaphora's headless Chrome-based connector can navigate, +authenticate, and capture any web application. ## Capture Modes ### Basic Mode Simple single-URL capture: + 1. Select a connector (Kibana, Grafana, Generic URL) 2. Enter the URL -3. Configure authentication -4. Set time range (for dashboards) -5. Capture +3. Configure authentication (if needed) +4. Capture Best for: Quick dashboard snapshots, simple reports. ### Advanced Mode Multi-step browser automation: + 1. Chain multiple navigation and capture actions 2. Extract data into variables 3. Evaluate conditions @@ -35,19 +37,20 @@ Toggle **Advanced** to switch modes. ### Kibana Connector -When you paste a Kibana URL, Anaphora automatically recognizes it and provides Kibana-specific options. +Use the Kibana connector to use Anaphora's built-in support for Kibana pages. **Supported Page Types:** + - Dashboards - Canvas workpads - Discover views +**Authentication:** +Login to Kibana using the ReadonlyREST login access. + **Time Range Configuration:** -| Option | Description | -|--------|-------------| -| Absolute | Specific date/time range | -| Relative | "Last 24 hours", "Last 7 days", etc. | -| Dashboard default | Use time range saved in dashboard | +Either set the time range in the Kibana UI before copying the URL, or set it in Anaphora using a similar syntax to +Kibana's time picker. **Capture Options:** | Mode | Description | @@ -56,48 +59,36 @@ When you paste a Kibana URL, Anaphora automatically recognizes it and provides K | **Per visualization** | Separate snapshot for each panel | :::tip Per-Visualization Capture -Capturing each visualization separately gives you more control in the Composer — arrange panels in custom layouts, exclude certain visualizations, or combine with other content. +Capturing each visualization separately gives you more control in the Composer — arrange panels in custom layouts, +exclude certain visualizations, or combine with other content. ::: -**Authentication Methods:** - -| Method | Description | -|--------|-------------| -| None | Public dashboards | -| ReadonlyREST login | Username/password with ReadonlyREST | -| Enterprise login | SSO with tenancy support | -| API key | For headless access | - ### Grafana Connector -Captures Grafana dashboards via the Grafana API. +Use the Grafana connector to use Anaphora's built-in support for Grafana pages. -**Configuration:** -| Field | Description | -|-------|-------------| -| URL | Grafana dashboard URL | -| API Key | Service account token | -| Time Range | Override dashboard time settings | -| Kiosk Mode | Cleaner capture without UI chrome | +**Authentication:** +Login with a Grafana user. Works for Grafana Cloud and self-hosted Grafana instances. **Capture Options:** + - Full dashboard capture - Panel-level capture (similar to Kibana per-visualization) ### Generic Web Connector -For any authenticated web application — if a human can reach it, Anaphora can capture it. +For any web page — if a human can reach it, Anaphora can capture it. **Use Cases:** + - Internal tools and dashboards - SaaS applications - Custom web applications -- Pages requiring complex login flows **Authentication:** -- Form-based login (username/password) -- SSO redirect flows -- Multi-factor authentication (with manual setup) + +- Natively supports Basic Auth headers +- Use Advanced mode to script login flows ## Advanced Capture Workflows @@ -107,36 +98,36 @@ Advanced mode enables multi-step browser automation for complex scenarios. ```mermaid flowchart LR - A["Navigate to URL"] --> B["Authenticate (if needed)"] + A["Navigate to URL"]] B --> C["Interact (click, type)"] C --> D["Capture (snapshot to var)"] ``` ### Browser Actions -| Action | Description | Example | -|--------|-------------|---------| -| **Navigate** | Go to a URL | Open dashboard | -| **Click** | Click an element | Expand menu, select filter | -| **Type** | Enter text | Search box, form field | +| Action | Description | Example | +|----------------------|------------------|----------------------------| +| **Navigate** | Go to a URL | Open dashboard | +| **Click** | Click an element | Expand menu, select filter | +| **Type** | Enter text | Search box, form field | | **Wait for visible** | Wait for element | Dashboard loading complete | -| **Wait** | Pause execution | Allow animations to finish | -| **Reload** | Refresh page | Clear cached state | +| **Wait** | Pause execution | Allow animations to finish | +| **Reload** | Refresh page | Clear cached state | ### Data Extraction Actions -| Action | Description | Example | -|--------|-------------|---------| -| **Capture value** | Extract text into variable | Error count, status text | -| **Capture snapshot** | Screenshot element to variable | Chart, panel, full page | -| **Calculate** | Arithmetic on variables | `$errors / $total * 100` | +| Action | Description | Example | +|----------------------|--------------------------------|--------------------------| +| **Capture value** | Extract text into variable | Error count, status text | +| **Capture snapshot** | Screenshot element to variable | Chart, panel, full page | +| **Calculate** | Arithmetic on variables | `errors / total * 100` | ### Control Flow Actions -| Action | Description | Example | -|--------|-------------|---------| -| **Conditional block** | If/else logic | Only notify if errors > 0 | -| **Break** | Stop without sending | Skip report if threshold not met | +| Action | Description | Example | +|-----------------------|----------------------|----------------------------------| +| **Conditional block** | If/else logic | Only notify if errors > 0 | +| **Break** | Stop without sending | Skip report if threshold not met | ### Example: Multi-Source Report @@ -144,16 +135,15 @@ Capture from multiple dashboards in one job: ``` 1. Navigate → Kibana Dashboard A -2. Capture snapshot → $dashboard_a +2. Capture snapshot → dashboard_a 3. Navigate → Grafana Dashboard B -4. Capture snapshot → $dashboard_b +4. Capture snapshot → dashboard_b 5. Navigate → Internal Tool 6. Click → "Generate Report" button -7. Wait for visible → Report table -8. Capture snapshot → $internal_report +7. Capture snapshot → internal_report ``` -Result: Three snapshots available in Composer as `$dashboard_a`, `$dashboard_b`, `$internal_report`. +Result: Three snapshots available in Composer as `dashboard_a`, `dashboard_b`, `internal_report`. ### Example: Conditional Alert @@ -161,13 +151,11 @@ Only send notification when error threshold is exceeded: ``` 1. Navigate → Error Dashboard -2. Capture value → $error_count (from error counter element) -3. Calculate → $threshold = 100 -4. Conditional block: - - If $error_count > $threshold: - - Capture snapshot → $alert_screenshot - - Else: +2. Capture value → error_count (from error counter element) +3. Conditional block: + - If error_count < 100: - Break (no notification sent) +4. Capture snapshot → error_dashboard ``` ## Authentication Best Practices @@ -175,20 +163,14 @@ Only send notification when error threshold is exceeded: ### Service Accounts For production jobs: + - Create dedicated service accounts with read-only access -- Use API keys where available (more stable than login flows) - Store credentials securely in Anaphora's encrypted database -### Handling SSO - -For complex SSO flows: -1. Use Advanced mode to manually navigate the login process -2. Add Wait actions between authentication steps -3. Test thoroughly — SSO flows can be timing-sensitive - ### Kibana with ReadonlyREST Anaphora has first-class support for ReadonlyREST authentication: + - Simple username/password login - Tenancy selection for multi-tenant Kibana - Enterprise SSO integration @@ -198,20 +180,21 @@ Anaphora has first-class support for ReadonlyREST authentication: ### Stable Captures For reliable automation: + - Use stable dashboard URLs (avoid temporary/session-based URLs) - Prefer consistent layouts — dynamic dashboards may produce varying results -- Add explicit Wait actions after navigation -- Use element-specific captures rather than full-page when possible +- Add wait actions when necessary to ensure content is fully loaded +- If possible use element-specific captures rather than full-page when possible ### Handling Failures - Configure retry policies in General tab -- Use Wait for visible before captures - Test captures manually before scheduling ## Testing Click **Test capture** to: + 1. Run the capture workflow immediately 2. Preview all captured snapshots 3. Verify authentication works @@ -219,7 +202,8 @@ Click **Test capture** to: 5. Debug any issues :::tip Debug Workflow -Use Test frequently while building Advanced workflows. Each action's result is visible, making it easy to identify where issues occur. +Use Test frequently while building Advanced workflows. Each action's result is visible, making it easy to identify where +issues occur. ::: ## Next Steps diff --git a/docs/jobs/composer.md b/docs/jobs/composer.md index 29da1ee..8bada95 100644 --- a/docs/jobs/composer.md +++ b/docs/jobs/composer.md @@ -1,253 +1,41 @@ --- sidebar_position: 3 description: Design professional PDF reports with Anaphora's block-based composer - layouts, branding, snapshots, and AI-generated content. -keywords: [PDF report builder, report composer, branded reports, PDF layout, report template] +keywords: [ PDF report builder, report composer, branded reports, PDF layout, report template ] --- # Composer - Report Builder -The Composer tab is where captured content becomes a professional report. Using a block-based editor, you can create branded PDFs with custom layouts, text, images, and snapshots. - -## Overview - -After capture, the Composer assembles your content into a deliverable format: - -```mermaid -flowchart TB - subgraph page["Report Page"] - header["**Header**
Logo | Title | Date"] - snapshots["**Snapshots**
$dashboard_a | $dashboard_b"] - ai["**AI Analysis**
$ai_summary"] - footer["**Footer**
Page 1 of 2"] - - header --> snapshots --> ai --> footer - end -``` +The Composer tab is where captured content becomes a professional report. Using a block-based editor, you can create +branded PDFs with custom layouts, text, images, and snapshots. ## Block Types -### Content Blocks - -| Block | Description | -|-------|-------------| -| **Snapshot** | Insert captured screenshot (from variable) | -| **Text** | Headings, paragraphs, metadata | -| **Image** | Logos, icons, decorative images | -| **AI Content** | AI-generated analysis or summary | - -### Layout Blocks - -| Block | Description | -|-------|-------------| -| **Columns** | Multi-column layouts (2, 3, or custom) | -| **Divider** | Horizontal line separator | -| **Spacer** | Vertical whitespace | -| **Page Break** | Force new page | - -### Structure Blocks - -| Block | Description | -|-------|-------------| -| **Header** | Repeating page header | -| **Footer** | Repeating page footer | -| **Container** | Grouping with background/border | - -## Block Editor - -### Adding Blocks - -1. Click **+ Add Block** or use the block palette -2. Select block type -3. Configure block properties -4. Drag to reposition - -### Block Properties - -Each block has configurable properties: - -**Text Block Properties:** -| Property | Options | -|----------|---------| -| Content | Text with variable support | -| Heading Level | H1, H2, H3, paragraph | -| Alignment | Left, center, right | -| Font Size | Custom or preset sizes | -| Color | Text color picker | - -**Snapshot Block Properties:** -| Property | Options | -|----------|---------| -| Variable | Select from captured snapshots | -| Size | Width/height or auto | -| Border | None, thin, medium | -| Caption | Optional text below image | - -**Container Properties:** -| Property | Options | -|----------|---------| -| Background | Color or image | -| Padding | Inner spacing | -| Border | Style, color, radius | -| Opacity | Transparency level | - -## Branding & Styling - -### Global Styles - -Set default styles for the entire report: - -| Setting | Description | -|---------|-------------| -| **Page Size** | A4, Letter, or custom dimensions | -| **Margins** | Top, bottom, left, right spacing | -| **Font Family** | Default typeface | -| **Colors** | Primary, secondary, accent colors | - -### Branded Reports - -Create professional branded reports: - -1. **Logo placement** — Header, footer, or watermark -2. **Color scheme** — Match corporate brand colors -3. **Typography** — Use brand-approved fonts -4. **Backgrounds** — Subtle patterns or gradients - -### Example: Corporate Template - -``` -Header: -├── Logo (left) -├── Report Title (center) -└── Date (right) - -Body: -├── Executive Summary (text) -├── Dashboard Snapshot (full width) -├── Two-Column Layout: -│ ├── Metrics Panel (left) -│ └── Trend Chart (right) -└── AI Analysis (text) - -Footer: -├── Company Name (left) -├── Page Number (center) -└── Confidentiality Notice (right) -``` - -## Template Variables - -Insert dynamic content using variables: - -### System Variables - -| Variable | Description | Example Output | -|----------|-------------|----------------| -| `{{date}}` | Report date | "January 15, 2025" | -| `{{time}}` | Report time | "09:30 AM" | -| `{{datetime}}` | Full timestamp | "2025-01-15 09:30:00" | -| `{{job_name}}` | Job name | "Daily Dashboard Report" | -| `{{job_id}}` | Job identifier | "job-123abc" | - -### Captured Variables - -Variables from the Capture workflow: - -| Syntax | Description | -|--------|-------------| -| `{{$snapshot_name}}` | Insert captured snapshot | -| `{{$value_name}}` | Insert captured text value | -| `{{$calculated}}` | Insert calculated result | - -### AI Variables - -When using AI providers: - -| Variable | Description | -|----------|-------------| -| `{{$ai_summary}}` | AI-generated summary | -| `{{$ai_analysis}}` | AI analysis of captured data | - -## Multi-Page Reports - -### Page Management - -- **Add Page** — Create additional pages -- **Page Order** — Drag pages to reorder -- **Page Break** — Force content to next page -- **Continuous** — Let content flow naturally - -### Page-Specific Content - -Each page can have: -- Different layouts -- Unique content blocks -- Shared headers/footers (optional) - -## Output Formats - -| Format | Use Case | Notes | -|--------|----------|-------| -| **PDF** | Email attachments, archival | Most common, best quality | -| **PNG** | Slack, chat apps | Single image, limited pages | -| **JPEG** | Smaller file size | Compressed, some quality loss | -| **HTML** | Web viewing | Interactive, larger file | - -## Templates - -### Saving Templates - -Save your composition as a reusable template: - -1. Design your report layout -2. Click **Save as Template** -3. Name and categorize -4. Reuse across jobs - -### Template Library - -- **Default templates** — Pre-built layouts -- **Custom templates** — Your saved designs -- **Shared templates** — Available within your Space - -## Preview & Testing - -### Preview Mode - -Click **Preview** to see the final rendered report: -- Actual PDF rendering -- Variable substitution -- Page breaks and layout -- Real captured content (if available) - -### Test Run - -For complete validation: -1. Run a test capture from Capture tab -2. Switch to Composer -3. Preview with actual data -4. Adjust layout as needed - -## Best Practices +### Capture Blocks -### Layout Tips +| Block | Description | +|---------------|-----------------------------------------------| +| **Snapshots** | All captured screenshots | +| **Variables** | Captured texts, calculated values, AI results | -- Use consistent margins and spacing -- Keep important content above the fold on page 1 -- Use page breaks to control pagination -- Test with different data volumes +### Component Blocks -### Performance +| Block | Description | +|-------------|----------------------------------------------------| +| **Text** | Add any text to the report. Can contain variables. | +| **Image** | Upload static images like logos | +| **Divider** | Horizontal line separator | +| **Spacer** | Vertical whitespace | -- Optimize image sizes before upload -- Limit complex layouts on high-frequency jobs -- Use appropriate output format for delivery channel +## Layout -### Accessibility +The report layout is built using a hierarchical structure of pages, rows, and cells. -- Use sufficient color contrast -- Include alt text for images -- Maintain readable font sizes -- Use clear heading hierarchy +| Structure | Description | +|-----------|---------------------------------------------------------------| +| **Page** | Pages reflect PDF pagination. Every page consists of rows. | +| **Row** | Rows split pages horizontally into sections. | +| **Cell** | Cells hold blocks within rows. Up to 3 cells can fit per row. | ## Next Steps diff --git a/docs/jobs/delivery.md b/docs/jobs/delivery.md index ef278e9..3a8962a 100644 --- a/docs/jobs/delivery.md +++ b/docs/jobs/delivery.md @@ -1,12 +1,13 @@ --- sidebar_position: 4 -description: Configure report delivery - email, Slack, webhooks, and S3 archiving. Multi-channel distribution and conditional routing. -keywords: [report delivery, email reports, Slack notifications, webhook, S3 archiving, report distribution] +description: Configure report delivery - email, webhooks, and S3 archiving. Multi-channel distribution and conditional routing. +keywords: [ report delivery, email reports, webhook, S3 archiving, report distribution ] --- # Delivery Configuration -The Delivery tab configures where and how reports are sent. Anaphora supports multi-channel delivery with conditional routing. +The Delivery tab configures where and how reports are sent. Anaphora supports multi-channel delivery via email, +webhooks, and S3 archiving. ## Overview @@ -18,7 +19,6 @@ flowchart LR subgraph channels["Delivery Channels"] email["Email"] - slack["Slack"] s3["S3"] webhook["Webhook"] end @@ -28,24 +28,23 @@ flowchart LR ## Delivery Interfaces -Delivery Interfaces are reusable destination configurations. Configure them once in Settings, then select them in any job. +Delivery Interfaces are reusable destination configurations. Configure them once in Settings, then select them in any +job. ### Available Types -| Interface | Best For | Features | -|-----------|----------|----------| -| **SMTP** | Corporate email | SSL/TLS, attachments | -| **Mailgun** | High-volume email | API-based, reliable | -| **Slack** | Team notifications | Channels, threads, images | -| **Webhook** | Integrations | Custom payloads, any endpoint | -| **S3** | Archival, compliance | Historical records, versioning | +| Interface | Best For | Features | +|-------------|----------------------|--------------------------------| +| **SMTP** | Corporate email | SSL/TLS, attachments | +| **Mailgun** | Transactional email | High volume, tracking | +| **Webhook** | Integrations | Custom payloads, any endpoint | +| **S3** | Archival, compliance | Historical records, versioning | ### Reusability You can configure multiple interfaces of each type: - Different SMTP servers for different teams -- Multiple Slack workspaces - Separate S3 buckets for different retention periods - Various webhooks for different integrations @@ -55,139 +54,49 @@ S3 is particularly valuable for historical archives and compliance workflows. ### Use Cases -| Scenario | Benefit | -|----------|---------| -| **Historical reference** | "What did this dashboard look like on date X?" | -| **Compliance evidence** | Immutable records for audit requirements | -| **Long-term retention** | Store reports beyond housekeeping limits | -| **Cross-system integration** | Other tools can access archived reports | - -### Configuration - -| Setting | Description | -|---------|-------------| -| Bucket | S3 bucket name | -| Region | AWS region | -| Path prefix | Folder structure for organization | -| Credentials | AWS access key or IAM role | - -### Organization Strategy - -Structure your S3 archive for easy retrieval: - -``` -s3://company-reports/ -├── anaphora/ -│ ├── daily-dashboards/ -│ │ ├── 2025/ -│ │ │ ├── 01/ -│ │ │ │ ├── 2025-01-15-dashboard.pdf -│ │ │ │ └── 2025-01-16-dashboard.pdf -│ ├── compliance-reports/ -│ │ └── ... -│ └── alerts/ -│ └── ... -``` +| Scenario | Benefit | +|------------------------------|------------------------------------------------| +| **Historical reference** | "What did this dashboard look like on date X?" | +| **Compliance evidence** | Immutable records for audit requirements | +| **Long-term retention** | Store reports beyond housekeeping limits | +| **Cross-system integration** | Other tools can access archived reports | ## Email Delivery -### SMTP Configuration - -| Setting | Description | -|---------|-------------| -| Host | SMTP server address | -| Port | Usually 587 (TLS) or 465 (SSL) | -| Security | None, SSL, or StartTLS | -| Authentication | Username/password | +Anaphora supports sending reports via SMTP or Mailgun. ### Email Options -| Field | Description | Supports Variables | -|-------|-------------|-------------------| -| From | Sender address | No | -| To | Recipients (comma-separated) | Yes | -| CC/BCC | Additional recipients | Yes | -| Subject | Email subject line | Yes | -| Body | Message content | Yes | -| Attachment | Include PDF report | - | - -### Example Subject Lines - -``` -Daily Dashboard Report - {{date}} -[ALERT] Error threshold exceeded - {{$error_count}} errors -Weekly Summary: {{job_name}} -``` - -## Slack Delivery - -### Slack Configuration - -| Setting | Description | -|---------|-------------| -| Workspace | Connected Slack workspace | -| Channel | Default destination channel | -| Thread | Reply to thread (optional) | - -### Message Options +| Field | Description | +|------------------|------------------------------------------------| +| Attachments | Whether to attach the PDF report to the email. | +| Message template | Customizable email body with variables. | +| Recipients | List of email addresses to send the report to. | -| Field | Description | -|-------|-------------| -| Channel | Override default channel | -| Message | Text message (supports Slack formatting) | -| Image | Embed report as image | -| PDF | Upload PDF as file | - -### Slack Formatting - -Use Slack's mrkdwn formatting: - -``` -*Daily Report* for {{date}} - -Dashboard shows {{$metric_count}} active users. - -See attached PDF for full details. -``` +:::tip Recipients +Recipient email addresses can be either marked as single user or as group address. Emails sent to single user addresses +will include a snooze and unsubscribe link in the footer. Group addresses will not include these links. +::: ## Webhook Delivery +Webhooks enable custom integrations with any HTTP endpoint. + ### Webhook Configuration -| Setting | Description | -|---------|-------------| -| URL | Endpoint to receive report | -| Method | POST (default) or PUT | -| Headers | Custom headers (auth, content-type) | -| Payload format | JSON, form-data, or raw | - -### Payload Structure - -Webhook payloads include: - -```json -{ - "job_name": "Daily Dashboard Report", - "job_id": "job-123abc", - "run_id": "run-456def", - "timestamp": "2025-01-15T09:30:00Z", - "status": "success", - "report_url": "https://anaphora.example.com/reports/...", - "variables": { - "$error_count": 42, - "$status": "warning" - } -} -``` +| Field | Description | +|--------------------|-----------------------------------------------------------------------------------------------| +| Message template | Customizable message body with variables. | +| JSON body template | Define the JSON payload with variables. Only available when enabled in the Webhook interface. | ### Webhook Use Cases -| Integration | Description | -|-------------|-------------| -| **Ticketing systems** | Create tickets for alerts | -| **Chat platforms** | Custom integrations beyond Slack | -| **Data pipelines** | Feed report data to analytics | -| **Custom dashboards** | Update external status pages | +| Integration | Description | +|-----------------------|----------------------------------------| +| **Ticketing systems** | Create tickets for alerts | +| **Chat platforms** | Create messages in collaboration tools | +| **Data pipelines** | Feed report data to analytics | +| **Custom dashboards** | Update external status pages | ## Multi-Channel Delivery @@ -203,93 +112,23 @@ Send the same report to multiple destinations: ### Example: Alert with Archive ``` -Delivery 1: Slack (immediate notification) +Delivery 1: Webhook e.g. Slack (immediate notification) Delivery 2: Email (stakeholder distribution) Delivery 3: S3 (permanent archive) ``` -## Conditional Delivery - -Combine with Advanced Capture to route reports based on conditions. - -### Routing by Severity - -``` -If $error_count > 100: - → Deliver to #critical-alerts (Slack) - → Deliver to oncall@company.com (Email) -Else if $error_count > 10: - → Deliver to #team-alerts (Slack) -Else: - → Archive only (S3) -``` - -### Routing by Content - -``` -If $region == "EMEA": - → Deliver to emea-team@company.com -Else if $region == "APAC": - → Deliver to apac-team@company.com -``` - -## Delivery Failure Handling - -### Retry Behavior - -If delivery fails: -1. Anaphora retries based on job retry policy -2. Failed deliveries are logged -3. Admin notification on persistent failures - ### Partial Success With multi-channel delivery: + - Each channel is attempted independently - Partial success (some channels succeed, others fail) is logged -- Successful deliveries are not re-attempted on retry ## Testing Delivery -### Test Run - -1. Click **Test** on the job -2. Run captures and compose -3. Deliver to configured channels -4. Verify receipt and formatting - -### Delivery Log - -Check delivery status in the Run log: -- Success/failure per channel -- Error messages for failures -- Timing information - -## Best Practices - -### Email - -- Use distribution lists for team delivery -- Test subject lines with variables -- Consider time zones for delivery timing - -### Slack - -- Use dedicated channels for automated reports -- Include context in messages (what, when, why) -- Consider thread replies for high-frequency alerts - -### S3 - -- Implement lifecycle policies in AWS for old files -- Use consistent naming conventions -- Enable versioning for compliance requirements - -### Webhooks - -- Implement retry/idempotency on receiving end -- Use authentication headers for security -- Log incoming webhooks for debugging +Every delivery config includes a **Test** button. Use it to verify configuration before saving the job. +All steps during the capture and delivery process are logged for troubleshooting. +Use debug mode to also receive a video of the capture process. ## Next Steps diff --git a/docs/jobs/general.md b/docs/jobs/general.md index cfa93b3..4db3145 100644 --- a/docs/jobs/general.md +++ b/docs/jobs/general.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Configure job scheduling, notification throttling, retry policies, and data retention settings in Anaphora. -keywords: [job scheduling, CRON, notification throttling, retry policy, housekeeping, data retention] +keywords: [ job scheduling, CRON, notification throttling, retry policy, housekeeping, data retention ] --- # General Settings @@ -10,44 +10,38 @@ The General tab defines how often a job runs, how noisy it is allowed to be, and ## Configuration Fields -| Field | Description | Required | -|-------|-------------|----------| -| Name | Job identifier shown in lists and reports | Yes | -| Description | Notes about the job's purpose | No | -| Frequency | How often to run (simple or CRON) | Yes | -| Max Notify Frequency | Minimum time between notifications | No | -| Retry Policy | Behavior on capture failures | No | -| Housekeeping | Automatic cleanup of old runs/reports | No | +| Field | Description | Required | +|----------------------|-------------------------------------------|----------| +| Name | Job identifier shown in lists and reports | Yes | +| Description | Notes about the job's purpose | No | +| Frequency | How often to run (simple or CRON) | Yes | +| Max Notify Frequency | Minimum time between notifications | No | +| Retry Policy | Behavior on capture failures | No | +| Housekeeping | Automatic cleanup of old runs/reports | No | ## Scheduling ### Simple Frequency -Set how often the job should run using natural intervals: - -| Interval | Example Use Case | -|----------|------------------| -| Every X minutes | High-frequency alerting (5-10 min) | -| Every X hours | Regular status checks | -| Every X days | Daily reports | -| Every X weeks | Weekly summaries | +Set how often the job should run using natural intervals. ### Advanced (CRON) Toggle **Advanced** to use CRON expressions for precise scheduling: -| CRON Expression | Description | -|-----------------|-------------| -| `0 9 * * *` | Every day at 9:00 AM | -| `0 */2 * * *` | Every 2 hours | -| `0 9 * * 1-5` | Weekdays at 9:00 AM | -| `0 0 1 * *` | First day of every month | -| `*/10 * * * *` | Every 10 minutes | -| `0 9,17 * * *` | At 9:00 AM and 5:00 PM | +| CRON Expression | Description | +|-----------------|--------------------------| +| `0 9 * * *` | Every day at 9:00 AM | +| `0 */2 * * *` | Every 2 hours | +| `0 9 * * 1-5` | Weekdays at 9:00 AM | +| `0 0 1 * *` | First day of every month | +| `*/10 * * * *` | Every 10 minutes | +| `0 9,17 * * *` | At 9:00 AM and 5:00 PM | ## Notification Throttling -**Max Notify Frequency** controls the maximum notification rate regardless of how often the job runs. This is especially important for high-frequency alerting jobs. +**Max Notify Frequency** controls the maximum notification rate regardless of how often the job runs. This is especially +important for high-frequency alerting jobs. ### Why Throttling Matters @@ -78,82 +72,39 @@ flowchart TD ### Example Configuration -| Job Frequency | Throttling | Result | -|---------------|------------|--------| -| Every 5 minutes | 3 hours | Max 8 notifications/day | -| Every 10 minutes | 1 hour | Max 24 notifications/day | -| Every hour | 6 hours | Max 4 notifications/day | -| Daily | None | 1 notification/day | +| Job Frequency | Throttling | Result | +|------------------|------------|--------------------------| +| Every 5 minutes | 3 hours | Max 8 notifications/day | +| Every 10 minutes | 1 hour | Max 24 notifications/day | +| Every hour | 6 hours | Max 4 notifications/day | +| Daily | None | 1 notification/day | :::tip Alerting Pattern High-frequency sampling + throttling creates an alerting-style workflow: + - Job runs every 5 minutes to detect issues quickly - Throttling prevents notification fatigue - Recipients get timely alerts without spam -::: + ::: ## Retry Policy -Configure how Anaphora handles failed captures: - -| Setting | Description | -|---------|-------------| -| **Retry Count** | Number of retry attempts before giving up | -| **Retry Delay** | Wait time between retries | -| **Suspend on Failure** | Disable job after X consecutive failures | - -### Example: Resilient Configuration - -``` -Retry Count: 3 -Retry Delay: 30 seconds -Suspend After: 5 consecutive failures -``` - -This configuration: -1. Retries a failed capture up to 3 times -2. Waits 30 seconds between attempts -3. Suspends the job if 5 runs in a row fail (prevents endless failures) - -### Failure Notifications - -When failures occur: -- Admin receives notification based on retry/suspend settings -- Failed runs are logged with error details -- Job can be manually re-enabled after fixing issues +Enable retries to retry failed runs automatically after failures. +When enabled, set how many times the run should be retried before giving up. ## Housekeeping (Data Retention) -Control automatic deletion of old data to manage storage: - -| Setting | Description | Example | -|---------|-------------|---------| -| **Run History** | How long to keep execution logs | 30 days | -| **Reports** | How long to keep generated PDFs | 90 days | -| **Artifacts** | How long to keep captures/snapshots | 7 days | - -### Retention Strategies - -| Job Type | Recommended Retention | -|----------|----------------------| -| Alerting (high-frequency) | Short: 7-14 days | -| Daily reports | Medium: 30-60 days | -| Compliance reports | Long: 1+ year | -| Development/testing | Minimal: 1-7 days | +Enable run expire time to automatically delete old runs and reports after a specified period. +This helps manage storage usage over time. :::warning Storage Impact High-frequency jobs generate more data. Without housekeeping: + - 10-minute job = 144 runs/day = 4,320 runs/month - Each run may include snapshots and reports - Storage can grow rapidly without retention limits ::: -### Per-Job vs Global Housekeeping - -- **Per-Job**: Configure in the General tab for job-specific retention -- **Global**: Set system-wide defaults in Administration settings -- Per-job settings override global defaults - ## Best Practices ### For Scheduled Reports @@ -170,7 +121,7 @@ Housekeeping: 90 days ```yaml Frequency: Every 5-10 minutes Throttling: 1-3 hours (balance speed vs. noise) -Retry: 2 attempts (fail fast) +Retry: Job runs often enough; retries usually not needed Housekeeping: 14 days (less storage needed) ``` @@ -180,7 +131,7 @@ Housekeeping: 14 days (less storage needed) Frequency: Weekly or monthly Throttling: None Retry: 5 attempts (ensure success) -Housekeeping: 365+ days (or use S3 archiving) +Housekeeping: Never ``` ## Next Steps diff --git a/docs/jobs/index.md b/docs/jobs/index.md index 0295eca..5cebfa2 100644 --- a/docs/jobs/index.md +++ b/docs/jobs/index.md @@ -84,7 +84,7 @@ Capture Dashboard -> Send to AI -> Receive Analysis -> Include in Report - **Visual Analysis** - Pass screenshots to AI models to evaluate dashboard content - **Text Summaries** - AI generates human-readable summaries of complex data - **Anomaly Detection** - AI identifies unusual patterns or concerning trends -- **DeepSeek Compatible** - Works with any AI provider using the DeepSeek API format +- **OpenAI Compatible** - Works with any AI provider using the OpenAI API format ## Visual Composer diff --git a/sidebars.ts b/sidebars.ts index 8838111..a452c43 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -25,7 +25,7 @@ const sidebars: SidebarsConfig = { items: [ 'basic-examples/kibana-dashboard-report', 'basic-examples/kibana-alert', - 'basic-examples/conditional-report', + 'basic-examples/kibana-conditional-report', 'basic-examples/grafana-dashboard-report', ], }, @@ -38,9 +38,8 @@ const sidebars: SidebarsConfig = { }, items: [ 'advanced-examples/mixed-sources-report', - 'advanced-examples/kibana-statistical-alert', + 'advanced-examples/kibana-anomaly-alert', 'advanced-examples/ai-news-collation', - 'advanced-examples/branded-reports', ], }, { diff --git a/versioned_docs/version-stable/administration/ai-providers.md b/versioned_docs/version-stable/administration/ai-providers.md index 041324e..f3c8259 100644 --- a/versioned_docs/version-stable/administration/ai-providers.md +++ b/versioned_docs/version-stable/administration/ai-providers.md @@ -1,12 +1,13 @@ --- sidebar_position: 3 description: Configure AI providers in Anaphora for intelligent report analysis - GPT-5.2, Claude 4.5, Grok 4, DeepSeek V3, Qwen3, Llama 4, and self-hosted options. -keywords: [AI providers, GPT-5, Claude 4.5, Grok 4, DeepSeek V3, Qwen3, Llama 4, vLLM, LLM integration, AI analysis] +keywords: [ AI providers, GPT-5, Claude 4.5, Grok 4, DeepSeek V3, Qwen3, Llama 4, vLLM, LLM integration, AI analysis ] --- # AI Providers -Configure AI providers to enable intelligent analysis, content generation, and anomaly detection in your reports. Anaphora supports any provider implementing the OpenAI-compatible API specification. +Configure AI providers to enable intelligent analysis, content generation, and anomaly detection in your reports. +Anaphora supports any provider implementing the OpenAI-compatible API specification. ## Overview @@ -32,196 +33,25 @@ flowchart LR api -- "Analysis result" --> job ``` -## OpenAI-Compatible API - -Anaphora works with any provider implementing the OpenAI API specification. This includes: - -| Provider | Description | Self-Hosted | -|----------|-------------|-------------| -| **OpenAI** | GPT-5.2, GPT-5.1 models | No | -| **Anthropic** | Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 | No | -| **xAI** | Grok 4, Grok 3 models | No | -| **Azure OpenAI** | Microsoft-hosted OpenAI models | No | -| **DeepSeek** | DeepSeek-V3.2, cost-effective reasoning | No | -| **vLLM** | Self-hosted open-source models | Yes | -| **Ollama** | Local model runner | Yes | -| **LM Studio** | Desktop model runner | Yes | - ## Configuration ### Adding a Provider -1. Navigate to **Settings** > **AI Providers** +1. Navigate to **AI Providers** 2. Click **Add Provider** 3. Configure the connection: -| Field | Description | Example | -|-------|-------------|---------| -| **Name** | Identifier for this provider | `Production GPT-5` | -| **API Endpoint** | OpenAI-compatible base URL | `https://api.openai.com/v1` | -| **API Key** | Authentication token | `sk-...` (stored encrypted) | -| **Default Model** | Model to use if not specified | `gpt-5.2` | +| Field | Description | Example | +|--------------|-------------------------------------------------------|--------------------------------| +| **Name** | Identifier for this provider | `Production GPT-5` | +| **Provider** | Type of AI provider | `OpenAI`, `DeepSeek`, `Custom` | +| **Endpoint** | OpenAI-compatible base URL (Only for custom provider) | `https://api.openai.com/v1` | +| **API Key** | Authentication token | `sk-...` (stored encrypted) | +| **Model** | Model to use. Needs API key to fetch suggestions. | `gpt-5.2` | 4. Test the connection 5. Save -### Multiple Providers - -Configure multiple providers for different use cases: - -``` -Provider: DeepSeek-V3 -├── Endpoint: https://api.deepseek.com/v1 -├── Model: deepseek-v3.2 -└── Use for: Complex analysis, reasoning tasks - -Provider: vLLM-Qwen -├── Endpoint: http://vllm.internal:8000/v1 -├── Model: Qwen3-32B-Instruct -└── Use for: High-volume processing, cost control - -Provider: OpenAI-GPT5 -├── Endpoint: https://api.openai.com/v1 -├── Model: gpt-5.2 -└── Use for: Critical reports, best quality - -Provider: Anthropic-Claude -├── Endpoint: https://api.anthropic.com/v1 -├── Model: claude-sonnet-4.5 -└── Use for: Coding analysis, agentic tasks -``` - -### Multiple Models per Provider - -Each provider can expose multiple models: - -| Provider | Available Models | -|----------|-----------------| -| OpenAI | `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.1` | -| Anthropic | `claude-opus-4.5`, `claude-sonnet-4.5`, `claude-haiku-4.5` | -| xAI | `grok-4`, `grok-4-heavy`, `grok-3`, `grok-3-mini` | -| DeepSeek | `deepseek-v3.2`, `deepseek-r1` | -| vLLM | Depends on deployed models (Qwen3, Llama 4, etc.) | - -## Provider Types - -### DeepSeek - -Cost-effective models with strong reasoning capabilities. DeepSeek-V3.2 integrates thinking directly into tool-use. - -**Configuration:** -``` -Name: DeepSeek -Endpoint: https://api.deepseek.com/v1 -API Key: sk-xxxxx -Default Model: deepseek-v3.2 -``` - -**Available Models:** -- `deepseek-v3.2` — Latest flagship, thinking + tool-use integration -- `deepseek-v3.1` — Hybrid model combining V3 and R1 strengths -- `deepseek-r1` — Advanced reasoning, complex analysis - -### vLLM (Self-Hosted) - -Run open-source models on your infrastructure for data privacy and cost control. - -**Configuration:** -``` -Name: vLLM Internal -Endpoint: http://vllm-server.internal:8000/v1 -API Key: (optional, depends on deployment) -Default Model: Qwen3-32B-Instruct -``` - -**Popular Models for vLLM:** -- `Qwen3-32B-Instruct` — Strong general purpose, 128K context -- `Qwen3-235B-A22B` — Massive MoE model (22B active params) -- `Llama-4-Maverick` — Meta's multimodal MoE (17B active, 400B total) -- `Llama-4-Scout` — 10M context window (17B active, 109B total) -- `Qwen3-Coder-480B` — State-of-the-art coding (35B active) - -**Benefits:** -- Complete data privacy — data never leaves your infrastructure -- No per-token costs after initial setup -- Customizable model selection -- Low latency for internal networks - -### OpenAI - -Direct integration with OpenAI's API. GPT-5.2 is the current flagship with Instant, Thinking, and Pro variants. - -**Configuration:** -``` -Name: OpenAI -Endpoint: https://api.openai.com/v1 -API Key: sk-proj-xxxxx -Default Model: gpt-5.2 -``` - -**Available Models:** -- `gpt-5.2` — Latest flagship, best for coding and agentic tasks -- `gpt-5.2-codex` — Optimized for agentic coding workflows -- `gpt-5.1` — Previous generation (Instant and Thinking variants) - -### Anthropic Claude - -State-of-the-art models for coding, agents, and complex reasoning. Claude 4.5 series offers excellent cost-performance. - -**Configuration:** -``` -Name: Anthropic -Endpoint: https://api.anthropic.com/v1 -API Key: sk-ant-xxxxx -Default Model: claude-sonnet-4.5 -``` - -**Available Models:** -- `claude-opus-4.5` — Flagship, long-horizon autonomous tasks ($5/$25 per M tokens) -- `claude-sonnet-4.5` — Best balance of quality and cost ($3/$15 per M tokens) -- `claude-haiku-4.5` — Fast and efficient ($1/$5 per M tokens) - -### xAI Grok - -Strong reasoning models with real-time knowledge. Grok 4 is the latest flagship with 1M token context. - -**Configuration:** -``` -Name: xAI Grok -Endpoint: https://api.x.ai/v1 -API Key: xai-xxxxx -Default Model: grok-4 -``` - -**Available Models:** -- `grok-4` — Latest flagship, strong reasoning and tool use -- `grok-4-heavy` — Maximum capability variant -- `grok-3` — Previous generation, good cost-performance balance -- `grok-3-mini` — Fast responses, lower cost - -### Azure OpenAI - -Enterprise deployment through Microsoft Azure. - -**Configuration:** -``` -Name: Azure OpenAI -Endpoint: https://your-resource.openai.azure.com -API Key: xxxxx -Default Model: gpt-5 (deployment name) -``` - -## Space-Level Configuration - -AI Providers are configured per Space for isolation: - -| Space | AI Provider | Use Case | -|-------|-------------|----------| -| Production | OpenAI GPT-5.2 | Critical reports, highest quality | -| Development | vLLM Qwen3 | Testing, iteration | -| Client-Acme | DeepSeek V3.2 | Cost-effective analysis | -| Client-Beta | Claude Sonnet 4.5 | Balanced quality and cost | - ### Provider Inheritance - Each Space can have its own AI provider configuration @@ -230,25 +60,29 @@ AI Providers are configured per Space for isolation: ## Using AI in Jobs -### Composer Integration +### Job Capture Integration -Add AI-generated content blocks in the Composer: +Use AI actions in the job actions: -1. Add an **AI Analysis** block -2. Select the analysis type: - - **Summary** — Condense captured data - - **Trends** — Identify patterns over time - - **Anomalies** — Highlight unusual values - - **Custom** — Provide your own prompt +1. Edit or create a job +2. Navigate to the **Capture** tab +3. Enable advanced mode to use actions. +4. Add **AI** action +5. Configure: -3. Configure the prompt (for custom analysis) -4. Preview the output +| Field | Description | +|---------------|-----------------------------------------| +| Variable Name | Name of the variable to store AI output | +| Provider | Select the AI provider to use | +| Prompt | Define the prompt with instructions | +| Output type | Text, HTML, Number | +| Context | Choose what to include as context | ### Example: Dashboard Summary ``` -Block: AI Analysis -Type: Summary +Context: Dashboard snapshot showing system performance metrics +Type: Text Prompt: "Summarize the key metrics from this dashboard, highlighting any values that exceed normal ranges." @@ -261,70 +95,14 @@ Output: "System performance remains stable with 99.8% uptime. ### Example: Anomaly Detection ``` -Block: AI Analysis -Type: Anomaly Detection Context: Error rate visualization captured from Kibana +Type: Number +Prompt: "Identify any anomalies in the error rate data. Respond with 0 if none found. Return 1 if anomalies are detected." -Output: "⚠️ Anomaly detected: Error rate spiked to 4.2% between - 09:15-09:45 UTC, significantly above the 0.5% baseline. - This correlates with the deployment at 09:12 UTC visible - in the deployment timeline panel." +Output: 0 ``` -## Best Practices - -### Provider Selection - -| Use Case | Recommended Provider | -|----------|---------------------| -| **Security-sensitive data** | Self-hosted vLLM (Qwen3, Llama 4) | -| **Cost-sensitive high volume** | DeepSeek V3.2 or vLLM | -| **Best quality analysis** | OpenAI GPT-5.2 or Claude Opus 4.5 | -| **Coding and agentic tasks** | Claude Sonnet 4.5 or GPT-5.2-Codex | -| **Compliance requirements** | Azure OpenAI or self-hosted | - -### Prompt Engineering - -For consistent results: - -- Be specific about the desired output format -- Provide context about what the data represents -- Specify the audience (technical vs. executive) -- Include examples of good output when possible - -### Cost Management - -- Use appropriate models for each task (don't use Opus 4.5 for simple summaries — use Haiku 4.5) -- Set token limits for responses -- Monitor usage through provider dashboards -- Consider self-hosted options for high-volume use cases (Qwen3, Llama 4) - -### Reliability - -- Configure fallback providers for critical jobs -- Test AI features in development Spaces first -- Set reasonable timeout values -- Handle AI failures gracefully (jobs should complete even if AI fails) - -## Troubleshooting - -### Connection Issues - -| Issue | Solution | -|-------|----------| -| Connection timeout | Check endpoint URL, verify network access | -| 401 Unauthorized | Verify API key is correct and active | -| 429 Rate Limited | Reduce request frequency, upgrade plan | -| Model not found | Check model name matches provider's offerings | - -### Quality Issues - -| Issue | Solution | -|-------|----------| -| Poor analysis quality | Improve prompts, try different model | -| Inconsistent outputs | Add more specific instructions | -| Missing context | Ensure captured data is included | -| Hallucinations | Use more constrained prompts | +Use the output to add a condition in your job workflow for alerting. ## Next Steps diff --git a/versioned_docs/version-stable/administration/authentication/index.md b/versioned_docs/version-stable/administration/authentication/index.md index 496c14b..96c0703 100644 --- a/versioned_docs/version-stable/administration/authentication/index.md +++ b/versioned_docs/version-stable/administration/authentication/index.md @@ -1,114 +1,64 @@ --- sidebar_position: 1 description: Configure Anaphora authentication - local users, LDAP, SAML SSO, OpenID Connect, and session management. -keywords: [authentication, LDAP, SAML, SSO, OpenID Connect, OIDC, session management, RBAC] +keywords: [ authentication, LDAP, SAML, SSO, OpenID Connect, OIDC, session management, RBAC ] --- # Authentication -Configure user authentication and access control for Anaphora. The platform supports enterprise-standard authentication methods for secure access. +Configure user authentication and access control for Anaphora. The platform supports enterprise-standard authentication +methods for secure access. ## Authentication Methods -| Method | Description | Best For | -|--------|-------------|----------| -| [Local](/administration/authentication/local) | Built-in username/password | Small teams, testing | -| [LDAP](/administration/authentication/ldap) | Active Directory integration | Enterprise Windows environments | -| [SAML](/administration/authentication/saml) | Single Sign-On via SAML 2.0 | Okta, Azure AD, OneLogin | -| [OIDC](/administration/authentication/oidc) | OpenID Connect providers | Google, Auth0, Keycloak | +| Method | Description | Best For | +|-----------------------------------------------|------------------------------|---------------------------------| +| [Local](/administration/authentication/local) | Built-in username/password | Small teams, testing | +| [LDAP](/administration/authentication/ldap) | Active Directory integration | Enterprise Windows environments | +| [SAML](/administration/authentication/saml) | Single Sign-On via SAML 2.0 | Okta, Azure AD, OneLogin | +| [OIDC](/administration/authentication/oidc) | OpenID Connect providers | Google, Auth0, Keycloak | ## Roles and Permissions Anaphora uses role-based access control (RBAC). -### Built-in Roles +### User types -| Role | Permissions | -|------|-------------| -| **Admin** | Full access: users, settings, all Spaces | -| **Editor** | Create and edit jobs, run reports | -| **Viewer** | View reports and job status only | +Anaphora has two main user types: System users and normal users. System users will have global access and can manage the +Anaphora instance. While normal users will be assigned to specific spaces with permissions scoped to those spaces. -### Permission Details - -| Permission | Admin | Editor | Viewer | -|------------|-------|--------|--------| -| View reports | Yes | Yes | Yes | -| Create jobs | Yes | Yes | No | -| Edit jobs | Yes | Yes | No | -| Delete jobs | Yes | No | No | -| Manage delivery interfaces | Yes | Yes | No | -| Manage users | Yes | No | No | -| Manage Spaces | Yes | No | No | -| System settings | Yes | No | No | - -### Custom Roles - -Create custom roles with specific permissions: - -1. Go to **Settings** > **Roles** -2. Click **Create Role** -3. Select permissions to include -4. Save and assign to users - -## Session Management - -Administrators have visibility and control over user sessions. - -### Active Sessions - -View all active user sessions: - -| Information | Description | -|-------------|-------------| -| User | Logged-in user | -| IP Address | Client IP | -| Login Time | When session started | -| Last Activity | Most recent action | -| Device/Browser | Client information | +| User Type | Description | Methods | +|-----------------|--------------------------------------------|---------| +| **System user** | Full global access, manage system settings | Local | +| **Normal user** | Access and manage resources within spaces | All | -### Session Controls +### Space Permissions -| Action | Description | -|--------|-------------| -| **View sessions** | See all active sessions | -| **Force logout** | Terminate specific session | -| **Logout all** | Terminate all sessions for a user | +Users are assigned permissions within specific spaces: -### Session Policies +| Permission | Description | +|---------------|------------------------------------| +| **Admin** | Full access within assigned spaces | +| **ReadWrite** | Create and edit jobs, run reports | +| **Readonly** | View reports and job status only | -Configure session behavior: - -| Setting | Description | -|---------|-------------| -| Session timeout | Auto-logout after inactivity | -| Maximum sessions | Limit concurrent sessions per user | -| Remember me duration | Extended session lifetime | - -### Security Events - -Audit log captures authentication events: - -- Login success/failure -- Logout events -- Password changes -- Session terminations -- Permission changes - -## Best Practices - -### Security - -- Use SSO when available for centralized access control -- Require strong passwords for local accounts -- Review active sessions regularly -- Set appropriate session timeouts - -### Enterprise Integration +### Permission Details -- Use dedicated service accounts for LDAP binding -- Map groups to roles for automated permission management -- Test authentication changes in staging first +| Rights | System User | Space Admin | Space ReadWrite | Space Readonly | +|----------------------------|-------------|-------------|-----------------|----------------| +| View reports | Yes | Yes | Yes | Yes | +| View runs | Yes | Yes | Yes | Yes | +| Manage jobs | Yes | Yes | Yes | No | +| Manage delivery interfaces | Yes | Yes | No | No | +| Manage AI providers | Yes | Yes | No | No | +| Manage users | Yes | No | No | No | +| Manage spaces | Yes | No | No | No | +| Global settings | Yes | No | No | No | + +### Add User Permissions + +See the [Spaces](/administration/spaces) documentation for details on assigning users to spaces with specific +permissions. ## Next Steps diff --git a/versioned_docs/version-stable/administration/authentication/ldap.md b/versioned_docs/version-stable/administration/authentication/ldap.md index 53b8635..3ccc579 100644 --- a/versioned_docs/version-stable/administration/authentication/ldap.md +++ b/versioned_docs/version-stable/administration/authentication/ldap.md @@ -1,12 +1,14 @@ --- sidebar_position: 2 description: Configure LDAP and Active Directory authentication for Anaphora enterprise deployments. -keywords: [LDAP, Active Directory, AD, directory integration, enterprise authentication] +keywords: [ LDAP, Active Directory, AD, directory integration, enterprise authentication ] --- # LDAP / Active Directory -Connect to your enterprise directory for centralized user management. Supports Microsoft Active Directory, OpenLDAP, and other LDAP-compliant directories. +Connect to your enterprise directory for centralized user management. Supports Microsoft Active Directory, OpenLDAP, and +other LDAP-compliant directories. +![](images/ldap.png) ## Overview @@ -19,85 +21,40 @@ LDAP integration provides: ## Configuration -Navigate to **Settings** > **Authentication** > **LDAP** to configure. +Navigate to **Settings** > **System Settings** > **Auth** > **LDAP** to configure. + +| Field | Description | Example | Required | +|---------------------|--------------------------------|----------------------------------------|----------| +| URL | LDAP server address | `ldap://ldap.forumsys.com:389` | Yes | +| Bind DN | Service account for binding | `cn=read-only-admin,dc=example,dc=com` | Yes | +| Bind credentials | Service account password | (stored securely) | Yes | +| Search base | Base DN for user search | `dc=example,dc=com` | Yes | +| Search filter | LDAP filter for user lookup | `uid={{username}}` | Yes | +| Group search base | Base DN for group search | `ou=groups,dc=example,dc=com` | No | +| Group search filter | LDAP filter for groups | `(member={{cn}})` | No | +| Group name property | Attribute for group name | `cn` | No | +| Reject unauthorized | Enforce TLS certificate checks | `false` (unchecked) | No | +| CA | Certificate authority | base64-encoded PEM | No | +| Key | Client private key | base64-encoded PEM | No | +| Certificate | Client certificate | base64-encoded PEM | No | + +### Group to Role Mapping + +Use the group search to retrieve LDAP groups and map them to Anaphora roles. +In the **group search filter**, use `{{}}` placeholders to reference attributes from the login user. +Use the **Group name property** to specify which attribute will be used as the mapped role name. -### Connection Settings - -| Field | Description | Example | -|-------|-------------|---------| -| Server URL | LDAP server address | `ldaps://ldap.company.com:636` | -| Base DN | Search base for users | `dc=company,dc=com` | -| Bind DN | Service account for queries | `cn=anaphora,ou=service,dc=company,dc=com` | -| Bind Password | Service account password | (stored encrypted) | -| Connection Timeout | Max connection wait time | `10` seconds | -| Read Timeout | Max response wait time | `30` seconds | - -### User Search Settings - -| Field | Description | Example | -|-------|-------------|---------| -| User Base DN | Where to search for users | `ou=users,dc=company,dc=com` | -| User Filter | LDAP query for users | `(&(objectClass=user)(sAMAccountName={0}))` | -| Username Attribute | Attribute for login | `sAMAccountName` | - -### Group Settings (Optional) - -| Field | Description | Example | -|-------|-------------|---------| -| Group Base DN | Where to search for groups | `ou=groups,dc=company,dc=com` | -| Group Filter | Query for user's groups | `(&(objectClass=group)(member={0}))` | -| Group Name Attribute | Attribute for group name | `cn` | - -## Attribute Mapping - -Map LDAP attributes to Anaphora user properties: - -| Anaphora Field | Active Directory | OpenLDAP | -|----------------|------------------|----------| -| Username | `sAMAccountName` | `uid` | -| Email | `mail` | `mail` | -| Display Name | `displayName` | `cn` | -| Groups | `memberOf` | `memberOf` | - -### Mapping Configuration - -``` -Username Attribute: sAMAccountName -Email Attribute: mail -Display Name Attribute: displayName -Group Membership Attribute: memberOf -``` - -## Group-Based Roles - -Map LDAP groups to Anaphora roles for automatic permission assignment. - -### Example Mappings - -``` -LDAP Group: CN=Anaphora-Admins,OU=Groups,DC=company,DC=com - → Anaphora Role: Admin - -LDAP Group: CN=Anaphora-Editors,OU=Groups,DC=company,DC=com - → Anaphora Role: Editor - -LDAP Group: CN=Anaphora-Viewers,OU=Groups,DC=company,DC=com - → Anaphora Role: Viewer -``` - -### Space Membership +### SSL/TLS Configuration -Map groups to Space access: +For secure connections use LDAPS (port 636): -``` -LDAP Group: CN=Team-Alpha,OU=Teams,DC=company,DC=com - → Space: Alpha Team Reports - → Role: Editor +| Protocol | Port | Security | +|----------|------|-------------------------------| +| LDAP | 389 | Unencrypted (not recommended) | +| LDAPS | 636 | SSL/TLS encrypted | +| StartTLS | 389 | Upgraded to TLS | -LDAP Group: CN=Team-Beta,OU=Teams,DC=company,DC=com - → Space: Beta Team Reports - → Role: Viewer -``` +Provide CA, Key, and Certificate fields for TLS client authentication if required by your LDAP server. ## Active Directory Specifics @@ -110,60 +67,12 @@ Create a dedicated service account for Anaphora: 3. Grant "Read all user information" permission 4. No need for admin privileges -### Common User Filters - -| Scenario | Filter | -|----------|--------| -| All users | `(&(objectClass=user)(sAMAccountName={0}))` | -| Enabled users only | `(&(objectClass=user)(sAMAccountName={0})(!(userAccountControl:1.2.840.113556.1.4.803:=2)))` | -| Specific OU | `(&(objectClass=user)(sAMAccountName={0})(memberOf=CN=Anaphora-Users,OU=Groups,DC=company,DC=com))` | - -### SSL/TLS Configuration - -Always use LDAPS (port 636) for secure connections: - -| Protocol | Port | Security | -|----------|------|----------| -| LDAP | 389 | Unencrypted (not recommended) | -| LDAPS | 636 | SSL/TLS encrypted | -| StartTLS | 389 | Upgraded to TLS | - -## Testing - -### Test Connection - -1. Click **Test Connection** to verify server connectivity -2. Verify "Connection successful" message -3. Check bind credentials are working - -### Test User Search - -1. Enter a known username -2. Click **Test User Search** -3. Verify user attributes are returned correctly - -### Test Authentication - -1. Enter test username and password -2. Click **Test Login** -3. Verify authentication succeeds and groups are retrieved - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Connection refused | Check server URL and port, verify firewall rules | -| Bind failed | Verify bind DN and password, check account is not locked | -| User not found | Check base DN and user filter, verify user exists | -| Groups not mapped | Verify group filter and group DN, check membership attribute | -| SSL certificate error | Import CA certificate or use trusted certificate | - ### Debug Mode Enable LDAP debug logging: -1. Go to **Settings** > **System** > **Logging** -2. Set LDAP log level to DEBUG +1. Go to **Settings** > **System Settings** > **General** > **General** +2. Set **Log Level** to `debug` 3. Reproduce the issue 4. Review logs for detailed LDAP communication diff --git a/versioned_docs/version-stable/administration/authentication/local.md b/versioned_docs/version-stable/administration/authentication/local.md index 6e077d1..76cf78c 100644 --- a/versioned_docs/version-stable/administration/authentication/local.md +++ b/versioned_docs/version-stable/administration/authentication/local.md @@ -1,19 +1,20 @@ --- sidebar_position: 1 description: Configure local authentication with Anaphora's built-in user database for username and password login. -keywords: [local authentication, user management, password policy, built-in users] +keywords: [ local authentication, user management, password policy, built-in users ] --- # Local Authentication + ![](images/local.png) -Default authentication using Anaphora's built-in user database. Ideal for small teams, testing environments, or deployments without enterprise identity providers. +Default authentication using Anaphora's built-in user database. Ideal for small teams, testing environments, or +deployments without enterprise identity providers. ## Overview Local authentication provides: - **Built-in user database** — No external dependencies -- **Password policies** — Configurable security requirements - **User management UI** — Easy administration - **Quick setup** — Works out of the box @@ -21,114 +22,55 @@ Local authentication provides: ### Adding Users -1. Navigate to **Settings** > **Users** -2. Click **Add User** +1. Navigate to **Settings** > **System Settings** > **Auth** > **Local** +2. Click **Add New User** 3. Enter username, email, and password -4. Assign roles and Space memberships -5. Save +4. Assign roles +5. Choose user type: Normal user or system user +6. Save ### User Properties -| Field | Description | Required | -|-------|-------------|----------| -| Username | Unique login identifier | Yes | -| Email | User email address | Yes | -| Display Name | Friendly name shown in UI | No | -| Password | Initial password | Yes | -| System Role | Access level for system settings | Yes | -| Roles | Assigned permissions | Yes | -| Spaces | Space memberships | No | +| Field | Description | Required | +|-------------|---------------------------------|----------| +| Username | Unique login identifier | Yes | +| Password | Initial password | Yes | +| Roles | Assigned permission groups | No | +| System Role | User or system user designation | Yes | ### System Role The **System Role** controls access to system-wide settings: -| Role | Description | -|------|-------------| -| **user** | Normal user, cannot access system settings | -| **system** | Can access and modify system settings | +| Role | Description | +|------------|--------------------------------------------------------------------------------| +| **user** | Normal user, cannot access system settings | +| **system** | Can access and modify system settings. Has automatically access to all spaces. | :::note -System settings include authentication configuration, AI providers, backup settings, and other global options. Most users should have the `user` role. +System settings include authentication configuration, space configuration, backup settings, and other global options. +Most users should have the `user` role. ::: -### Editing Users - -1. Go to **Settings** > **Users** -2. Click on the user to edit -3. Update properties as needed -4. Save changes +### Managing Local Users -### Removing Users - -1. Go to **Settings** > **Users** -2. Select the user to remove -3. Click **Delete** -4. Confirm deletion +All local users will be managed by the system user alone. Users cannot modify their own accounts. +System users can change the password or add roles to existing users. The system user can also delete the local users. :::warning Deleting a user removes their access immediately. Jobs created by the user will remain. ::: -## Password Policy - -Configure password requirements for local users: - -| Setting | Description | Recommended | -|---------|-------------|-------------| -| Minimum length | Required character count | 12+ characters | -| Complexity | Uppercase, lowercase, numbers, symbols | Enable all | -| Expiration | Force password change after X days | 90 days | -| History | Prevent reuse of recent passwords | Last 5 passwords | - -### Configuring Password Policy - -1. Go to **Settings** > **Security** -2. Navigate to **Password Policy** -3. Set requirements -4. Save - -### Password Change - -Users can change their own password: - -1. Click user menu (top right) -2. Select **Change Password** -3. Enter current and new password -4. Confirm - -Administrators can reset passwords: - -1. Go to **Settings** > **Users** -2. Select the user -3. Click **Reset Password** -4. Send reset link or set temporary password - ## When to Use Local Auth -| Scenario | Recommendation | -|----------|----------------| -| Small team (under 10 users) | Local auth is sufficient | -| Testing/development | Local auth for simplicity | -| No corporate IdP available | Local auth as primary method | -| Enterprise environment | Consider LDAP, SAML, or OIDC | -| Compliance requirements | Use enterprise SSO | - -## Best Practices - -- Use strong, unique passwords -- Enable password complexity requirements -- Set reasonable expiration periods -- Review user list regularly -- Remove inactive accounts promptly - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Forgot password | Admin can reset via Settings > Users | -| Account locked | Admin unlocks via Settings > Users | -| Login fails | Verify username and password case sensitivity | +| Scenario | Recommendation | +|-----------------------------|------------------------------| +| Small team (under 10 users) | Local auth is sufficient | +| Testing/development | Local auth for simplicity | +| No corporate IdP available | Local auth as primary method | +| System user | Local is required | +| Enterprise environment | Consider LDAP, SAML, or OIDC | +| Compliance requirements | Use enterprise SSO | ## Next Steps diff --git a/versioned_docs/version-stable/administration/backup.md b/versioned_docs/version-stable/administration/backup.md index ebcb341..f00d687 100644 --- a/versioned_docs/version-stable/administration/backup.md +++ b/versioned_docs/version-stable/administration/backup.md @@ -1,87 +1,80 @@ --- sidebar_position: 4 description: Back up Anaphora configuration, jobs, and reports. Schedule automatic backups and restore from backup files. -keywords: [Anaphora backup, configuration backup, disaster recovery, data protection, scheduled backup] +keywords: [ Anaphora backup, configuration backup, disaster recovery, data protection, scheduled backup ] --- # Backup -Protect your Anaphora configuration and data with regular backups. +Protect your Anaphora configuration and data with backups. There are three ways to back up your Anaphora instance: -## What to Back Up +1. **UI Export** - Use the UI to create and download backup files. +2. **API Export** - Use the API to programmatically export data. +3. **Docker Volume Backup** - For Docker deployments, back up the data volume directly. -| Component | Description | Priority | -|-----------|-------------|----------| -| Configuration | Jobs, templates, settings | Critical | -| Reports | Generated report files | Important | -| Database | User data, history | Critical | -| Credentials | Encrypted secrets | Critical | +:::tip +**UI Export** and **API Export** will only back up the configuration and data stored within Anaphora. +Report files are not included in these backups. So having a docker volume backup is recommended for complete data +protection. +::: -## Backup Methods +## UI Backup -### Built-in Backup +1. Access the **Settings** > **Data**. +2. Click **Export to file** to download a backup of the current configuration and data. +3. Store the backup file securely. -1. Navigate to **Settings** > **Backup** -2. Click **Create Backup** -3. Download the backup file -4. Store securely +### UI Import -### Scheduled Backups +1. Go to **Settings** > **Data** +2. Click **Import from file** +3. Upload the backup file -Configure automatic backups: - -| Setting | Description | -|---------|-------------| -| Frequency | Daily, weekly, monthly | -| Retention | Number of backups to keep | -| Location | Local or remote storage | -| Encryption | Encrypt backup files | - -### Docker Volume Backup +## Docker Volume Backup For Docker deployments, back up the data volume: ```bash docker run --rm \ - -v anaphora-data:/data \ + -v anaphora-content:/data/content \ + -v anaphora-storage:/data/storage \ -v $(pwd):/backup \ alpine tar czf /backup/anaphora-backup.tar.gz /data ``` -## Restore - -### From UI - -1. Go to **Settings** > **Backup** -2. Click **Restore** -3. Upload backup file -4. Confirm restoration - -### From Command Line +### Docker Volume Import ```bash docker run --rm \ - -v anaphora-data:/data \ + -v anaphora-content:/content \ + -v anaphora-storage:/storage \ -v $(pwd):/backup \ alpine tar xzf /backup/anaphora-backup.tar.gz -C / ``` -## Best Practices +## API Backup + +**Authentication**: Use basic auth headers with a system user. + +Get the backup via the following endpoint: + +``` +GET /guest/api/export +``` + +**Response**: A downloadable backup file in `.ana` format. -- Back up before upgrades -- Test restores regularly -- Store backups off-site -- Encrypt sensitive backups -- Document recovery procedures +### API Import -## Disaster Recovery +**Authentication**: Use basic auth headers with a system user. -Plan for disaster recovery: +Upload the backup file via the following endpoint: + +``` +POST /guest/api/import +``` -1. Identify critical data -2. Define recovery objectives (RTO/RPO) -3. Document procedures -4. Test recovery regularly +**Request Body**: `.ana` backup file as binary data. ## Next Steps diff --git a/versioned_docs/version-stable/administration/images/space-selector.png b/versioned_docs/version-stable/administration/images/space-selector.png new file mode 100644 index 0000000..6e49cc1 Binary files /dev/null and b/versioned_docs/version-stable/administration/images/space-selector.png differ diff --git a/versioned_docs/version-stable/administration/index.md b/versioned_docs/version-stable/administration/index.md index a93efe5..af87732 100644 --- a/versioned_docs/version-stable/administration/index.md +++ b/versioned_docs/version-stable/administration/index.md @@ -1,138 +1,28 @@ --- sidebar_position: 6 description: Anaphora administration guide - configure authentication (LDAP, SAML, SSO), manage multi-tenant spaces, monitor system health, and backup data. -keywords: [Anaphora admin, LDAP authentication, SAML SSO, multi-tenant reporting, system monitoring, backup, RBAC] +keywords: [ Anaphora admin, LDAP authentication, SAML SSO, multi-tenant reporting, system monitoring, backup, RBAC ] --- # Administration - Security, Multi-Tenancy & Operations -Manage Anaphora's security, multi-tenancy, monitoring, and backups. This section covers enterprise features for managing users, permissions, and system health. +Manage Anaphora's security, multi-tenancy, monitoring, and backups. This section covers enterprise features for managing +users, permissions, and system health. ## Topics -| Topic | Description | -|-------|-------------| -| [Authentication](/administration/authentication/) | User authentication and access control | -| [Spaces](/administration/spaces) | Multi-tenant workspace management | -| [AI Providers](/administration/ai-providers) | Configure AI for intelligent analysis | -| [Self Monitoring](/administration/self-monitoring) | System health and metrics | -| [Backup](/administration/backup) | Data backup and recovery | +| Topic | Description | +|----------------------------------------------------|----------------------------------------| +| [Authentication](/administration/authentication/) | User authentication and access control | +| [Spaces](/administration/spaces) | Multi-tenant workspace management | +| [AI Providers](/administration/ai-providers) | Configure AI for intelligent analysis | +| [Self Monitoring](/administration/self-monitoring) | System health and metrics | +| [Backup](/administration/backup) | Data backup and recovery | -## Spaces: Multi-Tenant Isolation +## System User -Anaphora uses a **Spaces** concept to manage multi-tenancy and permissions effectively. - -### Shared-Nothing Architecture - -Spaces act as isolated containers with complete separation: - -```mermaid -flowchart TB - subgraph anaphora["Anaphora"] - subgraph spaceA["Space A"] - a1["Jobs"] - a2["Reports"] - a3["Delivery"] - a4["Users"] - end - subgraph spaceB["Space B"] - b1["Jobs"] - b2["Reports"] - b3["Delivery"] - b4["Users"] - end - subgraph spaceC["Space C"] - c1["Jobs"] - c2["Reports"] - c3["Delivery"] - c4["Users"] - end - end -``` - -- **Complete isolation** - Jobs, Delivery Interfaces, AI Providers, and reports cannot be shared between spaces -- **Copy support** - Items can be copied between spaces when needed -- **Independent configuration** - Each space has its own settings and retention policies - -### Use Cases for Spaces - -| Scenario | Implementation | -|----------|----------------| -| **Team separation** | Each team gets their own space with dedicated jobs | -| **Client isolation** | MSPs create separate spaces per client | -| **Environment separation** | Dev, staging, and production spaces | -| **Department boundaries** | Finance, Engineering, Marketing each have isolated spaces | - -## Role-Based Access Control (RBAC) - -Anaphora provides granular permissions through roles. - -### Permission Levels - -| Level | Capabilities | -|-------|-------------| -| **Read-only** | View jobs, reports, and settings | -| **Read-write** | Create and modify jobs, run reports | -| **Admin** | Full control including user management and space settings | - -### Assignment Options - -Permissions can be assigned to: - -- **Individual users** - Direct permission grants -- **Groups** - Permissions inherited by all group members -- **Roles** - Reusable permission sets - -## Authentication Methods - -Anaphora supports enterprise-standard authentication: - -| Method | Description | -|--------|-------------| -| [Local](/administration/authentication/local) | Built-in username/password authentication | -| [LDAP](/administration/authentication/ldap) | Active Directory and other LDAP directories | -| [SAML](/administration/authentication/saml) | SSO with Okta, Azure AD, OneLogin, etc. | -| [OIDC](/administration/authentication/oidc) | OAuth 2.0 / OpenID Connect providers | - -### Session Management - -Administrators can: - -- View all active sessions -- Force logout of specific users -- Set session timeout policies -- Monitor login history - -## System Monitoring - -Monitor Anaphora's health and performance: - -### Health Endpoint - -A dedicated endpoint for monitoring tools (Prometheus, Nagios, etc.): - -- System status and uptime -- Job execution statistics -- Error rates and failures -- Resource utilization - -### Alerting - -Configure alerts when: - -- Job execution error rates become too high -- System resources are constrained -- Authentication failures spike -- Delivery channels fail - -## Backup & Recovery - -Protect your Anaphora configuration and data: - -- **Full system backup** - Export all jobs, settings, and configurations -- **Scheduled backups** - Automate regular backup creation -- **Point-in-time recovery** - Restore to a specific backup -- **Migration support** - Move between Anaphora instances +The first user created during setup is the system administrator with full privileges. Only system admins can access and +manage the global settings. ## Next Steps diff --git a/versioned_docs/version-stable/administration/self-monitoring.md b/versioned_docs/version-stable/administration/self-monitoring.md index 08c2696..4d3fe67 100644 --- a/versioned_docs/version-stable/administration/self-monitoring.md +++ b/versioned_docs/version-stable/administration/self-monitoring.md @@ -1,92 +1,34 @@ --- sidebar_position: 3 description: Monitor Anaphora health, performance, and job metrics. Configure alerts, access logs, and integrate with Prometheus. -keywords: [self monitoring, health check, Prometheus, metrics, job monitoring, performance, Anaphora monitoring] +keywords: [ self monitoring, health check, Prometheus, metrics, job monitoring, performance, Anaphora monitoring ] --- # Self Monitoring -Monitor Anaphora's health, performance, and operational metrics. +Monitor Anaphora's health, job and delivery success. ![](images/self-monitoring.png) -## Dashboard -Access the monitoring dashboard at **Settings** > **Monitoring**. +## Health Monitoring -## Key Metrics +Access the monitoring settings at **Settings** > **Application** > **Health Monitoring**. -### System Health +### Setup Health Alerts -| Metric | Description | -|--------|-------------| -| Uptime | Time since last restart | -| Memory | Current memory usage | -| CPU | Processor utilization | -| Disk | Storage consumption | +Configure email alerts when the system detects changes in job health status. -### Job Metrics - -| Metric | Description | -|--------|-------------| -| Jobs Active | Currently running jobs | -| Jobs Scheduled | Total scheduled jobs | -| Success Rate | Percentage of successful runs | -| Avg Duration | Average job execution time | - -### Delivery Metrics - -| Metric | Description | -|--------|-------------| -| Deliveries/Hour | Reports sent per hour | -| Delivery Success | Successful delivery rate | -| Queue Depth | Pending deliveries | - -## Alerts - -Configure alerts for system issues: - -1. Go to **Monitoring** > **Alerts** -2. Set thresholds for key metrics -3. Configure notification channel -4. Enable the alert - -### Recommended Alerts - -- Job failure rate > 10% -- Memory usage > 85% -- Disk usage > 90% -- Delivery queue > 100 - -## Logs - -Access system logs: -- Application logs -- Job execution logs -- Error logs -- Audit logs - -### Log Levels - -| Level | Description | -|-------|-------------| -| ERROR | Failures requiring attention | -| WARN | Potential issues | -| INFO | Normal operations | -| DEBUG | Detailed troubleshooting | - -## Prometheus Endpoint - -Export metrics to Prometheus: - -``` -GET /metrics -``` +1. Enable **Health Alerts**. +2. Select a delivery interface and recipient email. +3. Set **Health Check Frequency**: how often to check job health. +4. Set **Maximum Notification Frequency**: minimum time between alerts (Optional). +5. Click **Save**. ## Health API Query Anaphora's health status programmatically: ``` -GET /api/health +GET /guest/api/health ``` ### Response Format @@ -94,20 +36,6 @@ GET /api/health ```json { "jobs": [ - { - "id": "533aeb70-efcc-43cc-8953-78f9c8fdc728", - "name": "Kibana Dashboard Snapshot", - "description": "Takes a snapshot of a dashboard", - "cron": "5 4 * * *", - "healthStatus": "green", - "recentRuns": [ - { "runAt": "2026-01-15T04:05:00.050Z", "state": "success" }, - { "runAt": "2026-01-14T04:05:00.040Z", "state": "success" }, - { "runAt": "2026-01-13T04:05:00.043Z", "state": "success" }, - { "runAt": "2026-01-12T04:05:00.049Z", "state": "success" }, - { "runAt": "2026-01-11T04:05:00.044Z", "state": "success" } - ] - }, { "id": "79cf54b6-df32-4b09-84f4-708ecc72b7bc", "name": "Kibana Dashboard Snapshot", @@ -115,11 +43,26 @@ GET /api/health "cron": "5 4 * * *", "healthStatus": "green", "recentRuns": [ - { "runAt": "2026-01-15T04:05:00.041Z", "state": "success" }, - { "runAt": "2026-01-14T04:05:00.051Z", "state": "success" }, - { "runAt": "2026-01-13T04:05:00.034Z", "state": "success" }, - { "runAt": "2026-01-12T04:05:00.040Z", "state": "success" }, - { "runAt": "2026-01-11T04:05:00.034Z", "state": "success" } + { + "runAt": "2026-01-15T04:05:00.041Z", + "state": "success" + }, + { + "runAt": "2026-01-14T04:05:00.051Z", + "state": "success" + }, + { + "runAt": "2026-01-13T04:05:00.034Z", + "state": "success" + }, + { + "runAt": "2026-01-12T04:05:00.040Z", + "state": "success" + }, + { + "runAt": "2026-01-11T04:05:00.034Z", + "state": "success" + } ] } ], @@ -128,9 +71,9 @@ GET /api/health "id": "4d5fba03-561e-4503-bf4d-c41817133aca", "name": "My Delivery Interface", "type": "webhook", - "healthStatus": "gray", + "healthStatus": "green", "summary24Hours": { - "totalCount": 0, + "totalCount": 11, "errorCount": 0, "errors": [] } @@ -141,12 +84,12 @@ GET /api/health ### Health Status Values -| Status | Meaning | -|--------|---------| -| **green** | All recent runs successful | -| **yellow** | Some recent failures | -| **red** | Most recent runs failed | -| **gray** | No recent activity | +| Status | Meaning | +|------------|----------------------------| +| **green** | All recent runs successful | +| **yellow** | Some recent failures | +| **red** | All recent runs failed | +| **gray** | No recent activity | ## Next Steps diff --git a/versioned_docs/version-stable/administration/spaces.md b/versioned_docs/version-stable/administration/spaces.md index 087e7f9..2b27b8d 100644 --- a/versioned_docs/version-stable/administration/spaces.md +++ b/versioned_docs/version-stable/administration/spaces.md @@ -1,12 +1,15 @@ --- sidebar_position: 2 description: Configure Anaphora Spaces for multi-tenant isolation - separate jobs, reports, and permissions by team or project. -keywords: [multi-tenancy, Spaces, workspace isolation, team separation, RBAC] +keywords: [ multi-tenancy, Spaces, workspace isolation, team separation, RBAC ] --- # Spaces -Spaces provide multi-tenant workspace isolation in Anaphora. They act as "share-nothing" containers that completely separate resources between teams, projects, or tenants. +Spaces provide multi-tenant workspace isolation in Anaphora. They act as "share-nothing" containers that completely +separate resources between teams, projects, or tenants. + +![](images/spaces.png) ## Overview @@ -25,19 +28,16 @@ flowchart TB a1["15 Jobs"] a2["3 Delivery Interfaces"] a3["5 Users"] - a4["AI Provider"] end subgraph spaceB["Space B (Team Beta)"] b1["8 Jobs"] b2["2 Delivery Interfaces"] b3["3 Users"] - b4["AI Provider"] end subgraph spaceC["Space C (Clients)"] c1["50 Jobs"] c2["5 Delivery Interfaces"] c3["10 Users"] - c4["No AI"] end end ``` @@ -46,209 +46,103 @@ flowchart TB Users can belong to multiple Spaces with different roles. ::: -## Share-Nothing Architecture - -Spaces enforce complete isolation: - -| Isolated | Not Shared | -|----------|------------| -| Jobs | Jobs cannot access other Spaces' resources | -| Delivery Interfaces | Each Space configures its own | -| AI Providers | Per-Space AI configuration | -| Reports | Only visible within the Space | -| Run History | Isolated execution logs | -| Templates | Report templates per Space | - ### Copying Between Spaces While resources cannot be shared, they can be copied: -1. Export job configuration from Space A -2. Import into Space B -3. Reconfigure Space-specific settings (delivery, credentials) - -## Creating Spaces +1. In the jobs list, select the jobs to copy to another Space +2. Click **Copy to Space** +3. Choose target Space +4. If applicable, select to copy associated delivery interfaces -1. Navigate to **Settings** > **Spaces** -2. Click **Create Space** -3. Enter name and description -4. Configure default settings -5. Save +The same process applies to delivery interfaces. -### Space Settings - -| Setting | Description | -|---------|-------------| -| **Name** | Unique identifier for the Space | -| **Description** | Purpose/team using this Space | -| **Default Space** | Set as default for new users | -| **Retention Override** | Custom housekeeping rules | - -## User Assignment +## Creating Spaces -Assign users to Spaces with specific roles: +1. Navigate to **Settings** > **System Settings** > **Permissions** +2. Click **Add Space** +3. Enter the name of the Space ### Assignment Process -1. Open Space settings -2. Go to **Members** tab -3. Click **Add Member** -4. Select user or group -5. Assign role (Admin, Editor, Viewer) -6. Save +1. Click **Add Permission** +2. Select user or role +3. Assign permission (Admin, ReadWrite, Readonly) + +:::tip User Roles +Users can have roles assigned to them. These roles can then be assigned to Spaces for easier management. So it is not +necessary to assign each user individually. +::: ### Multi-Space Users -Users can belong to multiple Spaces: +Users can belong to multiple Spaces, by direct assignment or via roles: ``` User: alice@company.com -├── Space: Engineering → Role: Admin -├── Space: Marketing → Role: Viewer -└── Space: DevOps → Role: Editor -``` - -### Group-Based Assignment - -Assign entire groups to Spaces: - -``` -Group: Engineering Team -└── Space: Engineering → Role: Editor - -All members of "Engineering Team" get Editor access to Engineering Space +├── Space: Engineering → Permission: Admin +└── Space: Marketing → Permission: Readonly +Role: DevOps Team +└── Space: DevOps → Permission: ReadWrite ``` ## Switching Spaces -Users with access to multiple Spaces see a Space selector in the navigation. +You can switch between Spaces using the Space selector in the sidebar. -### Current Space Indicator +![space-selector.png](images/space-selector.png) -- Shows active Space name in header -- All operations apply to current Space -- Jobs, reports, settings are Space-specific - -### Quick Switch - -- Click Space selector -- Choose from available Spaces -- View updates immediately +All resources you create or manage will be scoped to the selected Space. ## Use Cases ### Team Separation -| Space | Purpose | -|-------|---------| +| Space | Purpose | +|-------------|--------------------------------------| | Engineering | Technical dashboards, system metrics | -| Marketing | Campaign dashboards, analytics | -| Executive | Summary reports, KPIs | -| DevOps | Infrastructure monitoring, alerts | +| Marketing | Campaign dashboards, analytics | +| Executive | Summary reports, KPIs | +| DevOps | Infrastructure monitoring, alerts | ### Client Isolation (MSP) For managed service providers: -| Space | Client | -|-------|--------| -| Client-Acme | Acme Corp reports | -| Client-Beta | Beta Inc reports | +| Space | Client | +|--------------|-------------------| +| Client-Acme | Acme Corp reports | +| Client-Beta | Beta Inc reports | | Client-Gamma | Gamma Ltd reports | Each client's data is completely isolated. ### Environment Separation -| Space | Environment | -|-------|-------------| -| Production | Live dashboards, real alerts | -| Staging | Test jobs, validation | -| Development | Experimental configurations | - -## Space-Level Settings - -Each Space can override global settings: - -### Retention Policies - -Configure per-Space housekeeping: - -| Setting | Global | Space Override | -|---------|--------|----------------| -| Report retention | 90 days | 365 days (compliance) | -| Run history | 30 days | 7 days (dev Space) | - -### Default Configurations - -Set Space-specific defaults: - -- Default delivery interface -- Default templates -- Default capture settings +| Space | Environment | +|-------------|------------------------------| +| Production | Live dashboards, real alerts | +| Staging | Test jobs, validation | +| Development | Experimental configurations | ## Administration -### Space Admins - -Space Admins can: - -- Manage jobs within their Space -- Configure Space-specific delivery interfaces -- View all reports in the Space -- Manage Space membership - -Space Admins cannot: - -- Access other Spaces (unless assigned) -- Modify global settings -- Create new Spaces - -### System Admins - -System Admins can: +Only system administrators can create and manage Spaces. Space admins can only manage resources within their assigned +Spaces. -- Create and delete Spaces -- Access all Spaces -- Manage global settings -- Override Space configurations +See [Authentication](authentication/index.md) for details on user roles and permissions. ## Best Practices -### Naming Conventions - -Use clear, consistent naming: - -``` -Good: Engineering, Marketing, Client-Acme -Bad: Space1, Test, Temp -``` - ### Permission Principle Assign minimal required permissions: -- Most users: Viewer (report access only) -- Job creators: Editor +- Most users: Space Readonly +- Job creators: Space ReadWrite - Team leads: Space Admin - IT/Operations: System Admin -### Regular Review - -- Audit Space membership quarterly -- Remove inactive users -- Review job configurations -- Check retention policies - -### Documentation - -Document each Space's purpose: - -- What team/project uses it -- What dashboards are captured -- Who receives reports -- Retention requirements - ## Next Steps - [Self Monitoring](./self-monitoring) - Monitor system health diff --git a/versioned_docs/version-stable/advanced-examples/ai-news-collation.md b/versioned_docs/version-stable/advanced-examples/ai-news-collation.md index e534564..8a2ae47 100644 --- a/versioned_docs/version-stable/advanced-examples/ai-news-collation.md +++ b/versioned_docs/version-stable/advanced-examples/ai-news-collation.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Use AI to aggregate, summarize, and deliver curated content from multiple sources with Anaphora. -keywords: [AI summarization, news aggregation, content curation, LLM reports, Anaphora AI] +keywords: [ AI summarization, news aggregation, content curation, LLM reports, Anaphora AI ] --- # AI News Collation @@ -23,50 +23,26 @@ Create a daily digest that collects articles from multiple sources and provides ### 1. Create the Job -Name it: "Daily Industry Digest" +1. Navigate to **Jobs** +2. Click **Create New Job** -### 2. Configure Multi-Source Capture +### 2. Configure Capture -``` -# Source 1: Tech news site -Navigate → https://news.example.com/industry -Capture value → .article-titles → $headlines1 - -# Source 2: Blog aggregator -Navigate → https://blogs.example.com/feed -Capture value → .post-summaries → $headlines2 - -# Source 3: Reddit/HN -Navigate → https://reddit.com/r/industry -Capture value → .post-titles → $headlines3 -``` - -### 3. AI Processing - -Configure AI summarization in the composition phase: -- Combine captured content -- Generate executive summary -- Highlight key trends -- Create actionable insights +1. Enable **Advanced** mode +2. Add multiple **Navigate** actions for each source: + - Ensure that **Take Snapshot** is checked +3. Add **AI** action to process captured content + - Set prompt to: + ``` + Summarize the following articles into an executive summary, highlighting key trends and actionable insights + ``` + - Ensure that all context is included ### 4. Compose the Digest -Structure your report: -1. AI-generated executive summary -2. Top stories by category -3. Trending topics -4. Full article links - -### 5. Deliver - -Send to subscribers via email with a clean, readable format. - -## Tips - -- Filter out duplicates across sources -- Set appropriate content length limits -- Include source attribution +1. Include the AI-generated summary +2. Add other text blocks as needed -## Next Steps +### 5. Configure Delivery -- [Branded Reports](./branded-reports) - Professional report styling +- Add delivery interface and configure recipients diff --git a/versioned_docs/version-stable/advanced-examples/branded-reports.md b/versioned_docs/version-stable/advanced-examples/branded-reports.md deleted file mode 100644 index 152d627..0000000 --- a/versioned_docs/version-stable/advanced-examples/branded-reports.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 4 -description: Create professional branded reports with custom logos, colors, and templates for external stakeholders. -keywords: [branded reports, custom templates, professional PDF, white-label reports, Anaphora branding] ---- - -# Branded Reports - -Create professional, branded reports for external stakeholders. - -## Goal - -Generate polished reports with your company's branding for client delivery. - -## Use Cases - -- Client-facing SLA reports -- Partner performance summaries -- Board presentations -- Compliance documentation - -## Branding Elements - -### Logo and Colors - -Configure your brand assets in Settings: -- Company logo (header/footer) -- Primary and secondary colors -- Font preferences - -### Report Templates - -Create custom templates that include: -- Branded header with logo -- Consistent color scheme -- Professional typography -- Branded footer with contact info - -## Steps - -### 1. Set Up Brand Assets - -1. Navigate to **Settings** > **Branding** -2. Upload your logo -3. Configure color palette -4. Set default fonts - -### 2. Create a Branded Template - -1. Go to **Templates** > **Create New** -2. Design your layout with brand elements -3. Add placeholder sections for dynamic content -4. Save as "Client Report Template" - -### 3. Create the Job - -1. Create a new job for client reporting -2. Configure capture for relevant metrics -3. Select your branded template in Composition -4. Add dynamic fields: client name, date range, etc. - -### 4. Configure Professional Delivery - -- Use PDF format for attachments -- Include personalized email body -- Consider adding cover page - -## Template Variables - -Use variables for personalization: - -| Variable | Description | -|----------|-------------| -| `{{client_name}}` | Client company name | -| `{{report_period}}` | Date range | -| `{{generated_date}}` | Report generation date | - -## Next Steps - -- [Jobs](../jobs/) - Deep dive into job configuration diff --git a/versioned_docs/version-stable/advanced-examples/index.md b/versioned_docs/version-stable/advanced-examples/index.md index c6ec4d7..78f055a 100644 --- a/versioned_docs/version-stable/advanced-examples/index.md +++ b/versioned_docs/version-stable/advanced-examples/index.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Advanced Anaphora examples - multi-source reports, statistical alerts, AI-powered news collation, and branded PDF reports for enterprise use. -keywords: [advanced Kibana reports, multi-source dashboards, statistical alerts, branded reports, AI report generation] +keywords: [ advanced Kibana reports, multi-source dashboards, statistical alerts, branded reports, AI report generation ] --- # Advanced Examples - Enterprise Reporting Scenarios @@ -10,12 +10,11 @@ Complex reporting scenarios demonstrating Anaphora's full capabilities. ## Available Examples -| Example | Description | -|---------|-------------| +| Example | Description | +|------------------------------------------------------------------|-----------------------------------------------------| | [Mixed Sources Report](./advanced-examples/mixed-sources-report) | Combine data from multiple Kibana/Grafana instances | -| [Kibana Statistical Alert](./advanced-examples/kibana-statistical-alert) | Alerts based on statistical analysis | -| [AI News Collation](./advanced-examples/ai-news-collation) | Aggregate and summarize content with AI | -| [Branded Reports](./advanced-examples/branded-reports) | Professional reports with custom branding | +| [Kibana Anomaly Alert](./advanced-examples/kibana-anomaly-alert) | Alerts based on anomaly analysis | +| [AI News Collation](./advanced-examples/ai-news-collation) | Aggregate and summarize content with AI | ## Prerequisites diff --git a/versioned_docs/version-stable/advanced-examples/kibana-anomaly-alert.md b/versioned_docs/version-stable/advanced-examples/kibana-anomaly-alert.md new file mode 100644 index 0000000..5434b5c --- /dev/null +++ b/versioned_docs/version-stable/advanced-examples/kibana-anomaly-alert.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 2 +description: Create sophisticated Kibana alerts based on statistical analysis and trend detection with Anaphora. +keywords: [ statistical alert, trend detection, Kibana analytics, anomaly detection, Anaphora statistics ] +--- + +# Kibana Anomaly Alert + +Create alerts based on deviation from previous data. + +:::tip Kibana Anomaly Detection Template +The **Kibana Anomaly Alert** Template demonstrates this example for the Kibana demo instance. You can use it as a +starting point for your own anomaly detection jobs. +::: + +## Goal + +Alert when metrics deviate significantly from the previous time window. + +## Use Cases + +- Anomaly detection for response times +- Traffic spike alerts +- Resource utilization warnings + +## Steps + +### 1. Create the Job + +1. Navigate to **Jobs** +2. Click **Create New Job** + +### 2. Configure General Settings + +- **Frequency**: Every 15 minutes +- **Max Notify Frequency**: 3 hours + +### 3. Configure Advanced Capture + +1. Enable **Advanced** mode +2. In the preexisting **Navigate**-action: + - select **Kibana** as the connector + - Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` + - Choose authentication method: **ReadonlyREST** and add credentials + - Set time range to 30 minutes to 15 minutes ago +3. Add a **Capture value** action to extract the metric to monitor: + - Set the **variable name** to something like `previous_value` + - Set **capture template** to `Kibana discover hits` + - Set **Variable type** to `Number` +4. Add another **Navigate** action to get the current value: + - select **Kibana** as the connector + - Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` + - Set time range to last 15 minutes +5. Add another **Capture value** action to extract the current metric: + - Set the **variable name** to something like `current_value` + - Set **capture template** to `Kibana discover hits` + - Set **Variable type** to `Number` +6. Add a **Calculate** action to compute the percentage change: + - Set **Variable name** to something like `percent_change` + - Set **Operation** to `round(abs((current_value - previous_value) / previous_value) * 100)` +7. Add a **Conditional block** to check if the percentage change is below the threshold: + - Choose **Variable**: `percent_change` + - Set **Condition operation** to `Lesser than` + - Set **Condition value** to `20` (for 20% change) +8. Inside the conditional block, add a **Break** action to stop execution if the condition is met (i.e., change is below + threshold) + +### 4. Configure Delivery + +- Add delivery interface and configure recipients + +## Next Steps + +- [AI News Collation](./ai-news-collation) - AI-powered content processing diff --git a/versioned_docs/version-stable/advanced-examples/kibana-statistical-alert.md b/versioned_docs/version-stable/advanced-examples/kibana-statistical-alert.md deleted file mode 100644 index 5d7a6f1..0000000 --- a/versioned_docs/version-stable/advanced-examples/kibana-statistical-alert.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -sidebar_position: 2 -description: Create sophisticated Kibana alerts based on statistical analysis and trend detection with Anaphora. -keywords: [statistical alert, trend detection, Kibana analytics, anomaly detection, Anaphora statistics] ---- - -# Kibana Statistical Alert - -Create alerts based on statistical analysis and trend detection. - -## Goal - -Alert when metrics deviate significantly from their normal baseline. - -## Use Cases - -- Anomaly detection for response times -- Traffic spike alerts -- Resource utilization warnings - -## Steps - -### 1. Create the Job - -Name it: "Response Time Anomaly Alert" - -### 2. Configure Advanced Capture - -``` -# Capture current value -Navigate → Kibana dashboard with avg response time -Capture value → [data-test-subj="avgResponseTime"] → $current - -# Capture baseline (you might get this from a saved search) -Navigate → Kibana baseline metrics -Capture value → [data-test-subj="baselineAvg"] → $baseline - -# Calculate deviation -Calculate → (($current - $baseline) / $baseline) * 100 → $deviation - -# Alert if deviation exceeds threshold -Conditional block → $deviation > 50: - ├── Capture snapshot → Full dashboard - └── Continue to delivery -Break -``` - -### 3. Configure Delivery - -- **Channel**: Slack or PagerDuty webhook -- **Message**: `Response time anomaly: {{$current}}ms ({{$deviation}}% above baseline)` - -### 4. Set Throttling - -Set appropriate throttling to avoid alert fatigue during prolonged incidents. - -## Advanced: Rolling Averages - -For more sophisticated analysis, consider: -- Capturing multiple time periods -- Calculating standard deviation -- Using percentile-based thresholds - -## Next Steps - -- [AI News Collation](./ai-news-collation) - AI-powered content processing diff --git a/versioned_docs/version-stable/advanced-examples/mixed-sources-report.md b/versioned_docs/version-stable/advanced-examples/mixed-sources-report.md index cfa37d8..026b3eb 100644 --- a/versioned_docs/version-stable/advanced-examples/mixed-sources-report.md +++ b/versioned_docs/version-stable/advanced-examples/mixed-sources-report.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Combine data from multiple sources like Kibana and Grafana into a single unified report using Anaphora. -keywords: [multi-source report, combined dashboard, Kibana Grafana, unified report, Anaphora advanced] +keywords: [ multi-source report, combined dashboard, Kibana Grafana, unified report, Anaphora advanced ] --- # Mixed Sources Report @@ -11,6 +11,7 @@ Create reports that combine data from multiple sources into a single deliverable ## Goal Generate a weekly executive report combining: + - Kibana: Application metrics dashboard - Grafana: Infrastructure health - Web page: Service status page @@ -25,46 +26,47 @@ Generate a weekly executive report combining: ### 1. Create a New Job -Name it: "Weekly Executive Summary" - -### 2. Configure Advanced Capture - -Build a multi-source workflow: - -``` -# Source 1: Kibana Application Metrics -Navigate → Kibana dashboard URL -Wait for visible → .dashboard-container -Capture snapshot → $appMetrics - -# Source 2: Grafana Infrastructure -Navigate → Grafana dashboard URL -Wait for visible → .react-grid-layout -Capture snapshot → $infraMetrics - -# Source 3: Status Page -Navigate → https://status.example.com -Capture snapshot → $statusPage -``` - -### 3. Configure Composition - -Arrange the three captures in your report template: -1. Header with date and title -2. Application metrics section -3. Infrastructure metrics section -4. Status page summary - -### 4. Deliver - -Send the combined report to your executive team. - -## Tips - -- Use consistent time ranges across sources -- Consider adding summary text between sections -- Test each source individually before combining - -## Next Steps - -- [Kibana Statistical Alert](./kibana-statistical-alert) - Advanced alerting +1. Navigate to **Jobs** +2. Click **Create New Job** + +### 2. Configure General Settings + +- **Frequency**: Weekly on Mondays at 8:00 AM + +### 3. Set Up Advanced Capture + +1. Enable **Advanced** mode to build a multi-capture workflow +2. Edit the preexisting **Navigate**-action: + - Select **Kibana** as the connector + - Enter your Kibana dashboard URL: + ``` + https://kibana.example.com/app/dashboards#/view/application-metrics + ``` + - Choose authentication method: **ReadonlyREST** and add credentials + - Ensure **Take Snapshot** is checked +3. Add a second **Navigate** action: + - Select **Grafana** as the connector + - Enter your Grafana dashboard URL: + ``` + https://grafana.example.com/d/xyz789/infrastructure-health?orgId=1 + ``` + - Set **Authentication** to `Grafana` and add credentials + - Ensure **Take Snapshot** is checked +4. Add a third **Navigate** action: + - Select **Web Page** as the connector + - Enter your service status page URL: + ``` + https://status.example.com + ``` + - No authentication needed + - Ensure **Take Snapshot** is checked + +### 4. Configure Composition + +1. Add all three captured snapshots to the report +2. Arrange them in the desired order +3. Add headers and explanatory text as needed + +### 4. Configure Delivery + +- Add delivery interface and configure recipients diff --git a/versioned_docs/version-stable/basic-examples/conditional-report.md b/versioned_docs/version-stable/basic-examples/conditional-report.md deleted file mode 100644 index 58a3e28..0000000 --- a/versioned_docs/version-stable/basic-examples/conditional-report.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -sidebar_position: 3 -description: Create intelligent alerts that trigger when conditions are met, with AI-powered root cause analysis and detailed PDF reports. -keywords: [Anaphora alerts, conditional alerting, AI root cause analysis, multi-system monitoring, intelligent notifications] ---- - -# Intelligent Alerting - -Create alerts that monitor your systems and notify you only when specific conditions are met — with AI-powered analysis to help identify root causes. - -## The Alerting Concept - -In Anaphora, **an alert is a conditional report**. Instead of sending notifications blindly, Anaphora: - -1. **Captures** data from one or more systems (dashboards, metrics, logs) -2. **Evaluates** conditions based on extracted values -3. **Analyzes** the situation using AI (optional) -4. **Delivers** a detailed PDF with context, not just a notification - -The result: operators receive actionable intelligence, not just "something is wrong." - -## Why PDF Alerts? - -Traditional alerting tools send a message: *"Error rate exceeded 5%"* - -Anaphora sends a **complete situation report**: -- Screenshots of affected dashboards at the moment of the issue -- Extracted metrics and values that triggered the alert -- AI-generated analysis suggesting possible root causes -- Historical context from multiple data sources - -## Use Cases - -| Scenario | What Anaphora Captures | AI Analysis | -|----------|------------------------|-------------| -| Error spike | Error dashboard + log samples | "Error pattern suggests database connection timeout" | -| Performance degradation | APM metrics + infrastructure stats | "CPU spike correlates with deployment at 14:32" | -| Security anomaly | Auth logs + network traffic | "Unusual login pattern from new geographic region" | -| Business threshold | Revenue dashboard + inventory | "Sales drop coincides with payment gateway errors" | - -## Example: Multi-System Alert - -Monitor your stack and get intelligent alerts when things go wrong. - -### 1. Create the Alert Job - -1. Navigate to **Jobs** > **Create New Job** -2. Name it: "Infrastructure Health Alert" -3. Set frequency: Every 5 minutes (`*/5 * * * *`) -4. Set throttling: 1 hour (avoid notification fatigue) - -### 2. Configure Multi-System Capture - -Toggle **Advanced** mode and build a workflow that checks multiple sources: - -``` -Navigate → Grafana infrastructure dashboard -Capture value → CPU usage element → $cpuUsage -Capture value → Error rate element → $errorRate -Capture snapshot → Dashboard overview - -Navigate → Kibana error logs -Capture value → Error count (last 5 min) → $recentErrors -Capture snapshot → Error log view - -Conditional block → $cpuUsage > 80 OR $errorRate > 5 OR $recentErrors > 100: - ├── AI Analysis → "Analyze these metrics and screenshots..." - └── (Continue to Compose/Deliver) -Break → (If all conditions are healthy, stop here) -``` - -### 3. Add AI Analysis - -In the capture workflow, add an **AI Analysis** action: - -``` -Prompt: "Analyze the captured dashboards and metrics: -- CPU: {{$cpuUsage}}% -- Error rate: {{$errorRate}}% -- Recent errors: {{$recentErrors}} - -Based on the visual data and these metrics, identify: -1. The most likely root cause -2. Which systems are affected -3. Recommended immediate actions" -``` - -The AI examines both the **screenshots** and the **extracted values** to provide contextual analysis. - -### 4. Compose the Alert Report - -Design a PDF that gives operators everything they need: - -- **Header**: Alert timestamp and severity -- **AI Summary**: Root cause analysis and recommendations -- **Dashboard Screenshots**: Visual state at time of alert -- **Raw Metrics**: Extracted values that triggered the alert -- **Context**: Links to relevant dashboards for further investigation - -### 5. Configure Delivery - -Send alerts to the right people: -- **Email**: On-call team with PDF attachment -- **Slack**: Alert channel with summary and PDF link -- **Webhook**: Integrate with PagerDuty, Opsgenie, or custom systems - -## How It Works - -```mermaid -flowchart LR - capture["Capture
Multi-system data"] - condition["Evaluate
Check thresholds"] - ai["AI Analysis
Root cause reasoning"] - compose["Compose
Build PDF report"] - deliver["Deliver
Notify operators"] - - capture --> condition - condition -->|"Thresholds exceeded"| ai - condition -->|"All healthy"| stop["Stop
No notification"] - ai --> compose --> deliver -``` - -The **Break** action stops execution when conditions are healthy. No alert fatigue — only actionable notifications. - -## Best Practices - -- **Combine sources**: Capture from multiple systems for complete context -- **Use throttling**: Prevent notification storms during ongoing incidents -- **Include raw data**: AI analysis is helpful, but operators need the numbers too -- **Set clear thresholds**: Start conservative, tune based on real incidents -- **Test the workflow**: Use the Test button to verify conditions trigger correctly - -## Next Steps - -- [Grafana Dashboard Report](./grafana-dashboard-report) - Add Grafana to your monitoring -- [AI Analysis](../advanced-examples/ai-news-collation) - More AI-powered workflows -- [Notification Throttling](../jobs/general#notification-throttling) - Control alert frequency diff --git a/versioned_docs/version-stable/basic-examples/grafana-dashboard-report.md b/versioned_docs/version-stable/basic-examples/grafana-dashboard-report.md index 1a9cd9c..9301e4c 100644 --- a/versioned_docs/version-stable/basic-examples/grafana-dashboard-report.md +++ b/versioned_docs/version-stable/basic-examples/grafana-dashboard-report.md @@ -1,7 +1,7 @@ --- sidebar_position: 4 description: Capture and deliver scheduled Grafana dashboard reports with Anaphora for infrastructure monitoring. -keywords: [Grafana report, dashboard capture, infrastructure monitoring, scheduled report, Anaphora Grafana] +keywords: [ Grafana report, dashboard capture, infrastructure monitoring, scheduled report, Anaphora Grafana ] --- # Grafana Dashboard Report @@ -16,46 +16,36 @@ Send a daily infrastructure health report from Grafana to your ops team. ### 1. Create a New Job -1. Navigate to **Jobs** > **Create New Job** -2. Name it: "Infrastructure Health Report" +1. Navigate to **Jobs** +2. Click **Create New Job** ### 2. Configure General Settings - **Frequency**: Daily at 7:00 AM -- **Description**: "Daily infrastructure metrics from Grafana" ### 3. Set Up Capture -1. Select **Grafana** as the connector (or Generic URL) +1. Select **Grafana** as the connector 2. Enter your Grafana dashboard URL: - ``` - https://grafana.example.com/d/abc123/infrastructure?orgId=1 - ``` -3. Configure authentication (API key or basic auth) -4. Set time range parameters in the URL if needed + ``` + https://grafana.example.com/d/abc123/infrastructure?orgId=1 + ``` +3. Set **Authentication** to `Grafana` and add credentials ### 4. Configure Composition 1. Choose how to arrange captured panels -2. Select PDF or image output format -3. Add custom header with date/time +2. Add texts or headers as needed ### 5. Set Up Delivery 1. Choose delivery interface (Email, Slack, etc.) 2. Configure recipients -3. Set appropriate subject/message ### 6. Test and Save Verify the capture looks correct and save. -## Tips for Grafana - -- Use the `kiosk=tv` URL parameter for cleaner captures -- Set explicit time ranges in URL for consistent reports -- Consider capturing individual panels for more control - ## Next Steps -- [Advanced Examples](../advanced-examples/) - Complex multi-source reports +- [Advanced Examples](../advanced-examples/) - Unlock more complex report scenarios diff --git a/versioned_docs/version-stable/basic-examples/index.md b/versioned_docs/version-stable/basic-examples/index.md index 266bbff..95f8571 100644 --- a/versioned_docs/version-stable/basic-examples/index.md +++ b/versioned_docs/version-stable/basic-examples/index.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Step-by-step Anaphora tutorials for Kibana PDF reports, Grafana dashboard scheduling, and conditional alerts. Practical examples with complete configurations. -keywords: [Kibana PDF report, Grafana scheduled report, dashboard alert, Elasticsearch report, tutorial] +keywords: [ Kibana PDF report, Grafana scheduled report, dashboard alert, Elasticsearch report, tutorial ] --- # Basic Examples - Kibana & Grafana Report Tutorials @@ -10,12 +10,12 @@ Learn Anaphora through practical examples. Each example walks you through creati ## Available Examples -| Example | Description | -|---------|-------------| -| [Kibana Dashboard Report](./basic-examples/kibana-dashboard-report) | Schedule a daily PDF report of your Kibana dashboard | -| [Kibana Alert](./basic-examples/kibana-alert) | Send notifications when conditions are met | -| [Conditional Report](./basic-examples/conditional-report) | Reports that only send when criteria match | -| [Grafana Dashboard Report](./basic-examples/grafana-dashboard-report) | Capture and deliver Grafana dashboards | +| Example | Description | +|-------------------------------------------------------------------------|------------------------------------------------------| +| [Kibana Dashboard Report](./basic-examples/kibana-dashboard-report) | Schedule a daily PDF report of your Kibana dashboard | +| [Kibana Alert](./basic-examples/kibana-alert) | Send notifications when conditions are met | +| [Kibana Conditional Report](./basic-examples/kibana-conditional-report) | Reports that only send when criteria match | +| [Grafana Dashboard Report](./basic-examples/grafana-dashboard-report) | Capture and deliver Grafana dashboards | ## Prerequisites diff --git a/versioned_docs/version-stable/basic-examples/kibana-alert.md b/versioned_docs/version-stable/basic-examples/kibana-alert.md index b098b3b..ba195e3 100644 --- a/versioned_docs/version-stable/basic-examples/kibana-alert.md +++ b/versioned_docs/version-stable/basic-examples/kibana-alert.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Create conditional Kibana alerts with Slack notifications when error thresholds are exceeded using Anaphora. -keywords: [Kibana alert, conditional notification, Slack alert, error threshold, Anaphora alerting] +keywords: [ Kibana alert, conditional notification, Slack alert, error threshold, Anaphora alerting ] --- # Kibana Alert @@ -10,11 +10,12 @@ Create an alert that notifies you when specific conditions are met in your Kiban ## Goal -Send a Slack notification when the error count in your logs exceeds 100 in the last hour. +Send a notification when the error count in your logs exceeds 100 in the last hour. ## Concept In Anaphora, **an alert is a conditional report**. You create alerts by: + 1. Capturing data from Kibana 2. Evaluating conditions 3. Only delivering the report when conditions are met @@ -23,38 +24,41 @@ In Anaphora, **an alert is a conditional report**. You create alerts by: ### 1. Create a New Job -1. Navigate to **Jobs** > **Create New Job** -2. Name it: "Error Rate Alert" +1. Navigate to **Jobs** +2. Click **Create New Job** ### 2. Configure General Settings - **Frequency**: Every 5 minutes (`*/5 * * * *`) -- **Throttling**: 1 hour (avoid notification fatigue) +- **Max notify frequency**: 3 hours (avoid notification fatigue) :::tip Why Throttling? -Even if errors persist every 5 minutes, you'll only get one notification per hour. +Even if errors persist every 5 minutes, you'll only get one notification in 3 hours. ::: -### 3. Set Up Advanced Capture +### 3. Set Up Capture + +1. Select **Kibana** as the connector +2. Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` +3. Choose authentication method: **ReadonlyREST** and add credentials +4. Check **Deliver report only if conditions are met** +5. Set Hits to be greater than `100` -1. Toggle **Advanced** mode on -2. Add actions: +### 4. Compose the Alert Report -``` -Navigate → Kibana Discover (filtered for errors, last 1 hour) -Wait for visible → .euiDataGrid__content -Capture value → [data-test-subj="discoverQueryHits"] → $errorCount -Conditional block → $errorCount > 100: - └── Capture snapshot → Dashboard screenshot -``` +1. Add a text block +2. Edit the text and include `{{kibanaDiscoverHits}}` to show the number of errors +3. Add headers and other text as needed -### 4. Configure Delivery +### 5. Configure Delivery -1. Select **Slack** as delivery interface -2. Choose the alert channel -3. Message: `Alert: {{$errorCount}} errors in the last hour` +1. Select a delivery interface +2. Modify the body: `Alert: {{kibanaDiscoverHits}} errors in the last hour` -### 5. Test and Save +### 6. Test and Save 1. **Test** the job to verify the workflow 2. Check that conditions evaluate correctly @@ -62,8 +66,11 @@ Conditional block → $errorCount > 100: ## Result -You'll receive Slack alerts only when error count exceeds your threshold, with at most one notification per hour. +You'll receive alerts only when error count exceeds your threshold, with at most one notification per hour. ## Next Steps -- [Conditional Report](./conditional-report) - More complex conditions +- [Kibana Conditional Report](./kibana-conditional-report) - Need to also take a dashboard screenshot when the condition is met? See + how to use actions for conditional reports. +- [Kibana Anomaly Alert](../advanced-examples/kibana-anomaly-alert.md) - Need to compare current events to previous + events for anomaly detection? See this example for triggering alerts when events deviate from normal patterns. diff --git a/versioned_docs/version-stable/basic-examples/kibana-conditional-report.md b/versioned_docs/version-stable/basic-examples/kibana-conditional-report.md new file mode 100644 index 0000000..5c2e403 --- /dev/null +++ b/versioned_docs/version-stable/basic-examples/kibana-conditional-report.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 3 +description: Create intelligent alerts that trigger when conditions are met, with AI-powered root cause analysis and detailed PDF reports. +keywords: [ Anaphora alerts, conditional alerting, AI root cause analysis, multi-system monitoring, intelligent notifications ] +--- + +# Kibana Conditional Report + +Create reports that will only be built and delivered when specific conditions are met. + +:::tip Kibana Conditional Snapshot Template +The **Kibana Conditional Snapshot** Template demonstrates this example for the Kibana demo instance. You can +use it as a starting point for your own conditional reporting jobs. +::: + +## Goal + +In this example, we will check the Kibana discover page for error logs. Then we will capture a snapshot of a dashboard. +The report with the captured dashboard will only be delivered if the number of errors exceeds a defined threshold. + +## Steps + +### 1. Create a new job + +1. Navigate to **Jobs** +2. Click **Create New Job** + +### 2. Configure General Settings + +- **Frequency**: Every hour +- **Max Notify Frequency**: 12 hours + +### 3. Set Up Capture + +1. Enable **Advanced** mode to build a conditional workflow +2. In the preexisting **Navigate**-action: + - select **Kibana** as the connector + - Enter your Kibana discover URL: + ``` + https://kibana.example.com/app/discover#/view/your-view-id + ``` + - Choose authentication method: **ReadonlyREST** and add credentials +3. Add a **Capture value** action to extract the number of error logs: + - Set the **variable name** to something like `error_count` + - Set **capture template** to `Kibana discover hits` + - Set **Variable type** to `Number` +4. Add a **Conditional block** to check if the error count is smaller than the threshold: + - Choose **Variable**: `error_count` + - Set **Condition operation** to `Lesser than` + - Set **Condition value** to `100` +5. Inside the conditional block, add a **Break** action to stop execution if the condition is met (i.e., error count is + below threshold) +6. Add another **Navigate** action + - Select **Kibana** as the connector + - Enter your Kibana dashboard URL: + ``` + https://kibana.example.com/app/dashboards#/view/your-dashboard-id + ``` + - Ensure that **Take Snapshot** is checked and set the configuration properly + +### 4. Compose the Report + +1. Add the captured snapshot +2. If desired, add a text block with the `{{error_count}}` variable to show the number of errors +3. Add headers and other text as needed + +### 5. Set Up Delivery + +1. Select **Email** as delivery interface (needs to be configured first in **Delivery Interfaces**) +2. Add recipient email addresses + +## Next Steps + +- [Grafana Dashboard Report](./grafana-dashboard-report) - Add Grafana to your monitoring +- [AI Analysis](../advanced-examples/ai-news-collation) - More AI-powered workflows diff --git a/versioned_docs/version-stable/basic-examples/kibana-dashboard-report.md b/versioned_docs/version-stable/basic-examples/kibana-dashboard-report.md index b7a7611..4cbc17e 100644 --- a/versioned_docs/version-stable/basic-examples/kibana-dashboard-report.md +++ b/versioned_docs/version-stable/basic-examples/kibana-dashboard-report.md @@ -1,13 +1,18 @@ --- sidebar_position: 1 description: Step-by-step tutorial to create a scheduled Kibana dashboard PDF report with email delivery in Anaphora. -keywords: [Kibana report tutorial, scheduled dashboard, PDF email, Anaphora example, dashboard automation] +keywords: [ Kibana report tutorial, scheduled dashboard, PDF email, Anaphora example, dashboard automation ] --- # Kibana Dashboard Report Create a scheduled report that captures your Kibana dashboard and delivers it via email. +:::tip Kibana Dashboard Snapshot Template +The **Kibana Dashboard Snapshot** Template demonstrates this example for the Kibana demo instance. You can use it as a +starting point for your own dashboard reporting jobs. +::: + ## Goal Send a daily PDF report of a Kibana dashboard to your team every morning at 9 AM. @@ -18,38 +23,35 @@ Send a daily PDF report of a Kibana dashboard to your team every morning at 9 AM 1. Navigate to **Jobs** in the sidebar 2. Click **Create New Job** -3. Enter a name: "Daily Dashboard Report" ### 2. Configure General Settings - **Frequency**: Daily at 9:00 AM (or use CRON: `0 9 * * *`) -- **Description**: "Morning dashboard snapshot for the team" ### 3. Set Up Capture 1. Select **Kibana** as the connector 2. Enter your dashboard URL: - ``` - https://your-kibana.example.com/app/dashboards#/view/abc123 - ``` -3. Choose authentication method (Basic or saved profile) + ``` + https://your-kibana.example.com/app/dashboards#/view/abc123 + ``` +3. Choose authentication method: **ReadonlyREST** and add credentials 4. Set time range: "Last 24 hours" ### 4. Configure Composition -1. Select a report template or use default -2. Preview the layout -3. Add header/footer if needed +1. Drag the captured dashboard snapshot into the layout +2. Add additional text blocks if needed +3. Adjust the layout for optimal viewing ### 5. Set Up Delivery -1. Select **Email** as delivery interface +1. Select **Email** as delivery interface (needs to be configured first in **Delivery Interfaces**) 2. Add recipient email addresses -3. Set subject line: `Daily Dashboard Report - {{date}}` ### 6. Test and Save -1. Click **Test** to run the job immediately +1. Use the test to send a sample report to your email 2. Verify the email arrives correctly 3. **Save** the job diff --git a/versioned_docs/version-stable/changelog.md b/versioned_docs/version-stable/changelog.md index de94fdd..74fc1d2 100644 --- a/versioned_docs/version-stable/changelog.md +++ b/versioned_docs/version-stable/changelog.md @@ -1,7 +1,7 @@ --- sidebar_position: 8 description: Anaphora release notes and changelog. New features, enhancements, bug fixes, and security updates for Kibana/Grafana report automation. -keywords: [Anaphora changelog, release notes, new features, updates, version history] +keywords: [ Anaphora changelog, release notes, new features, updates, version history ] --- # Changelog - Anaphora Release Notes @@ -15,115 +15,18 @@ All notable changes to Anaphora are documented here. - 🧐 **Enhancement** - Improvements to existing features - 🐞 **Fix** - Bug fixes ---- - -## [Unreleased] - -### 🚀 New Feature: Documentation restructure - -
-Complete reorganization of documentation structure - -The documentation has been restructured for better navigation and discoverability: -- New "Basic Examples" and "Advanced Examples" sections -- Dedicated "Jobs" section with detailed component documentation -- Expanded "Delivery Interfaces" with per-interface guides -- New "Administration" section for security and operations -- Added changelog page +## [0.9.0] - 2026-01-15 -
- ---- - -## [1.0.0] - 2024-12-01 - -### 🚀 New Feature: Kibana dashboard capture - -
-Automated screenshot capture from Kibana dashboards - -Anaphora can now capture screenshots from Kibana dashboards, Canvas workpads, and Discover pages. Features include: -- Automatic detection of Kibana page types -- Time range configuration -- Multiple authentication methods -- Full page or viewport capture modes - -
- -### 🚀 New Feature: Grafana support +### 🚀 New Feature: Grafana Connector
Capture and report on Grafana dashboards -Full support for Grafana dashboard capture: -- API key authentication -- Panel-level capture -- Time range parameter support -- Kiosk mode for cleaner captures - -
- -### 🚀 New Feature: Conditional alerts - -
-Send reports only when conditions are met - -Create alerts that only trigger when specific criteria match: -- Extract values from pages into variables -- Perform calculations on captured data -- Conditional execution blocks -- Break action to skip report delivery - -
- -### 🚀 New Feature: Multi-channel delivery - -
-Deliver reports via email, Slack, or webhooks - -Multiple delivery options: -- SMTP email with attachment support -- Mailgun API integration -- Slack workspace integration with rich formatting -- Webhook delivery for custom integrations - -
- -### 🚀 New Feature: Multi-tenant spaces - -
-Isolate jobs and reports by team or project - -Workspace isolation for enterprise deployments: -- Separate jobs and reports per space -- Role-based access control -- Independent retention policies -- User assignment to multiple spaces - -
- -### 🚀 New Feature: Authentication providers - -
-Support for LDAP, SAML, and local authentication - -Enterprise authentication options: -- Local username/password authentication -- LDAP/Active Directory integration -- SAML 2.0 SSO (Okta, Azure AD, OneLogin) -- Role mapping from identity providers - -
- -### 🚀 New Feature: Report templates and branding - -
-Custom branded reports for professional delivery +With the new Grafana connector, Anaphora supports an out-of-the-box experience for capturing Grafana dashboards. +Features include: -Brand your reports: -- Custom logo placement -- Color scheme configuration -- Template variables for personalization -- PDF and image output formats +- Configurable authentication using the Grafana credentials +- Capture entire dashboards with automatic waiting for panels to load +- Capture individual panels for granular reporting
diff --git a/versioned_docs/version-stable/data-retention/index.md b/versioned_docs/version-stable/data-retention/index.md index 7e4b986..37877a0 100644 --- a/versioned_docs/version-stable/data-retention/index.md +++ b/versioned_docs/version-stable/data-retention/index.md @@ -1,12 +1,13 @@ --- sidebar_position: 7 description: Manage Anaphora data retention - configure storage policies for report history, captured data, and audit logs. Automatic housekeeping and cleanup. -keywords: [data retention, report storage, audit logs, retention policy, storage management, housekeeping] +keywords: [ data retention, report storage, audit logs, retention policy, storage management, housekeeping ] --- # Data Retention - Report History & Storage Management -Anaphora stores captured data and generated reports for reference and auditing purposes. This section covers how data is stored, managed, and automatically cleaned up. +Anaphora stores captured data and generated reports for reference and auditing purposes. This section covers how data is +stored, managed, and automatically cleaned up. ## Overview @@ -15,113 +16,10 @@ The Data Retention section provides access to: - **Runs** - Execution history of your jobs, including successful captures, failures, and delivery status - **Reports** - Generated report documents and archives -## Data Types - -| Type | Description | Storage Impact | -|------|-------------|----------------| -| **Captures** | Raw screenshots and extracted data | High | -| **Reports** | Generated PDF and image documents | High | -| **Run History** | Execution logs and status records | Medium | -| **Variables** | Extracted values from capture workflows | Low | -| **Audit Logs** | User actions and system events | Low | - ## Housekeeping & Automatic Cleanup -Anaphora includes automatic housekeeping to manage storage usage over time. - -### Retention Rules - -Configure rules to automatically delete old data: - -```mermaid -flowchart LR - d1["Day 1"] --> d15["Day 15"] --> d30["Day 30"] --> d31["Day 31"] - d31 --> deleted["Deleted"] - - style d31 fill:#ff6b6b - style deleted fill:#ff6b6b -``` - -*Example: Keep only the last 30 days of reports* - -### Configuration Options - -| Setting | Description | Example | -|---------|-------------|---------| -| **Time-based** | Delete data older than X days | Keep last 30 days | -| **Count-based** | Keep only the last X reports | Keep last 100 reports | -| **Size-based** | Delete when storage exceeds limit | Max 10 GB per space | -| **Per-job rules** | Different retention per job type | Critical jobs: 90 days | - -### Housekeeping Schedule - -- Automatic cleanup runs on a configurable schedule -- Default: Daily at midnight (configurable) -- Manual trigger available for immediate cleanup -- Dry-run mode to preview what will be deleted - -## Storage Management - -### Per-Space Isolation - -Each Space maintains its own storage quota and retention policies: - -- Independent retention rules per space -- Storage usage tracking per space -- Alerts when approaching quota limits - -### Storage Metrics - -Monitor storage usage through: - -- Dashboard widgets showing current usage -- Historical trends of storage growth -- Breakdown by data type (captures, reports, logs) -- Projections based on current growth rate - -## Data Lifecycle - -```mermaid -flowchart LR - capture["Capture
Fresh data"] - store["Store
Active access"] - archive["Archive
Aged storage"] - delete["Delete
Expired cleanup"] - - capture --> store --> archive --> delete -``` - -1. **Capture** - New data is captured and stored -2. **Active** - Data is readily available for viewing and export -3. **Archive** - Older data may be compressed or moved to cold storage -4. **Cleanup** - Data exceeding retention policy is permanently deleted - -## Compliance Considerations - -For regulated environments: - -- **Audit trails** - Maintain logs of who accessed what data and when -- **Immutable logs** - System events cannot be modified or deleted -- **Export before delete** - Option to export data before automatic cleanup -- **Legal hold** - Suspend deletion for specific data sets - -## Best Practices - -### Recommended Retention Policies - -| Data Type | Recommended Retention | -|-----------|----------------------| -| Production reports | 90 days | -| Development/test reports | 7-14 days | -| Audit logs | 1 year | -| Run history | 30 days | - -### Storage Optimization - -- Use element-level capture instead of full-page when possible -- Configure appropriate image quality/compression -- Archive important reports externally before cleanup -- Review and adjust retention policies quarterly +Anaphora includes automatic housekeeping to manage storage usage over time. You can configure retention policies for +runs and reports in the job settings. ## Next Steps diff --git a/versioned_docs/version-stable/data-retention/reports.md b/versioned_docs/version-stable/data-retention/reports.md index 1582c3f..cd78305 100644 --- a/versioned_docs/version-stable/data-retention/reports.md +++ b/versioned_docs/version-stable/data-retention/reports.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Access and manage generated reports in Anaphora. Browse report history, configure retention, and download captured data. -keywords: [reports, report storage, report retention, PDF reports, captured data, Anaphora reports] +keywords: [ reports, report storage, report retention, PDF reports, captured data, Anaphora reports ] --- # Reports @@ -12,21 +12,8 @@ The Reports section provides access to all generated report documents and their ## Overview -Reports are the final output of your capture jobs. Each report contains: - -- Captured screenshots -- Extracted data and variables -- Applied templates and formatting -- Delivery timestamps and status - -## Report Types - -| Type | Description | -|------|-------------| -| Screenshot Report | Visual capture of target content | -| Data Report | Extracted values and metrics | -| Composite Report | Combined screenshots and data | -| Template Report | Formatted using custom templates | +Reports are the final output of your capture jobs. A report is a PDF document assembled from captured screenshots, +extracted data, and formatted content. ## Viewing Reports @@ -34,12 +21,9 @@ Access reports through: - **Run history** - View report from specific execution - **Report browser** - Browse all generated reports -- **Search** - Find reports by date, job, or content ## Report Storage -Reports are stored according to your retention policy settings. Configure: - -- **Retention period** - How long to keep reports -- **Storage location** - Local or cloud storage options -- **Archival rules** - Automatic archival of old reports +Most importantly, reports are delivered to configured destinations (email, Slack, S3, webhooks). +However, Anaphora also stores copies of generated reports for reference. +In the job configuration, you can set how long reports are retained. diff --git a/versioned_docs/version-stable/data-retention/runs.md b/versioned_docs/version-stable/data-retention/runs.md index c33c1cd..6cd1239 100644 --- a/versioned_docs/version-stable/data-retention/runs.md +++ b/versioned_docs/version-stable/data-retention/runs.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: View and debug job execution history in Anaphora. Track run statuses, identify failures, and review captured content. -keywords: [job runs, execution history, run status, debugging, job monitoring, Anaphora runs] +keywords: [ job runs, execution history, run status, debugging, job monitoring, Anaphora runs ] --- # Runs @@ -21,28 +21,9 @@ Every time a job executes, a **run** record is created. This allows you to: ## Run Statuses -| Status | Description | -|--------|-------------| -| Success | Job completed and report delivered | -| Partial | Some actions succeeded, others failed | -| Failed | Job execution failed | -| Skipped | Conditions not met, no report sent | - -## Viewing Run Details - -Select any run to view: - -- Execution timestamp -- Job configuration at time of run -- Captured screenshots and data -- Delivery status and logs -- Error messages (if any) - -## Debugging Failed Runs - -When a run fails, check: - -1. **Run logs** - Detailed execution trace -2. **Screenshots** - Visual state at failure point -3. **Network errors** - Connection or timeout issues -4. **Selector changes** - Target page structure may have changed +| Status | Description | +|-----------------|-----------------------------------------------------------------------| +| Success | Job completed and report delivered | +| Delivery issues | The report was created but could not be delivered to all destinations | +| Failed | Job execution failed | +| Skipped | Conditions not met, no report sent | diff --git a/versioned_docs/version-stable/delivery-interfaces/index.md b/versioned_docs/version-stable/delivery-interfaces/index.md index cb0bd8d..b024abb 100644 --- a/versioned_docs/version-stable/delivery-interfaces/index.md +++ b/versioned_docs/version-stable/delivery-interfaces/index.md @@ -1,46 +1,26 @@ --- sidebar_position: 5 description: Configure Anaphora delivery channels - send reports via SMTP email, Mailgun, Slack, webhooks, or S3 archiving. PDF export and multi-channel distribution. -keywords: [email reports, Slack reports, webhook delivery, SMTP configuration, Mailgun integration, S3 archiving, PDF export, report distribution] +keywords: [ email reports, Slack reports, webhook delivery, SMTP configuration, Mailgun integration, S3 archiving, PDF export, report distribution ] --- # Delivery Interfaces - Email, Slack, S3 & Webhook -Delivery Interfaces define how reports reach your recipients. Once a report is generated, Anaphora handles distribution through multiple channels simultaneously. +Delivery Interfaces define how reports reach your recipients. Once a report is generated, Anaphora handles distribution +through multiple channels simultaneously. ## Available Interfaces -| Interface | Description | Best For | -|-----------|-------------|----------| -| [SMTP](/delivery-interfaces/smtp) | Direct email via SMTP server | Corporate email systems | -| [Mailgun](/delivery-interfaces/mailgun) | Email via Mailgun API | High-volume delivery | -| [Slack](/delivery-interfaces/slack) | Slack workspace integration | Team notifications | -| [S3](/delivery-interfaces/s3) | S3-compatible object storage | Archiving & compliance | -| [WebHook](/delivery-interfaces/webhook) | Custom HTTP endpoints | Integrations & automation | - -## Output Formats - -Reports can be delivered in multiple formats: - -| Format | Description | Use Case | -|--------|-------------|----------| -| **PDF** | Portable document format | Formal reports, archiving, printing | -| **PNG/JPEG** | Image formats | Quick previews, Slack thumbnails | -| **HTML** | Web format | Interactive viewing, email body | -| **Raw data** | JSON payload | Webhook integrations, further processing | - -## PDF Export - -Generate professional PDF reports directly from Anaphora: - -- **View in browser** - Preview reports before delivery -- **Download** - Manual PDF export from the Reports section -- **Email attachment** - Automatically attach PDFs to email delivery -- **Custom styling** - Branded headers, footers, and page layouts +| Interface | Description | Best For | +|-----------------------------------------|------------------------------|---------------------------| +| [SMTP](/delivery-interfaces/smtp) | Direct email via SMTP server | Corporate email systems | +| [Mailgun](/delivery-interfaces/mailgun) | Email via Mailgun API | High-volume delivery | +| [S3](/delivery-interfaces/s3) | S3-compatible object storage | Archiving & compliance | +| [WebHook](/delivery-interfaces/webhook) | Custom HTTP endpoints | Integrations & automation | ## Configuration -1. Navigate to **Settings** > **Delivery Interfaces** +1. Navigate to **Delivery Interfaces** 2. Click **Add Interface** 3. Select type and configure credentials 4. Test the connection @@ -51,39 +31,7 @@ Generate professional PDF reports directly from Anaphora: Once configured, interfaces appear in the job's **Delivery** tab: - Select one or multiple delivery channels -- Configure per-channel settings (recipients, subject lines, etc.) -- Set delivery conditions (always, on success, on failure) - -## Multiple Interfaces - -You can configure multiple interfaces of the same type: - -| Scenario | Configuration | -|----------|---------------| -| **Different teams** | Separate Slack channels per team | -| **Backup delivery** | Primary SMTP + fallback Mailgun | -| **Regional separation** | Different email servers per region | -| **Integration variety** | Multiple webhooks for different systems | - -## Delivery Flow - -```mermaid -flowchart LR - report["Report Generated"] - - subgraph interfaces["Delivery Interfaces"] - email["Email"] - slack["Slack"] - s3["S3"] - webhook["Webhook"] - end - - report --> interfaces - email --> recipients["Recipients"] - slack --> channels["Channels"] - s3 --> bucket["S3 Bucket"] - webhook --> endpoints["Endpoints"] -``` +- Configure per-channel settings (recipients, notification body, etc.) ## Next Steps diff --git a/versioned_docs/version-stable/delivery-interfaces/mailgun.md b/versioned_docs/version-stable/delivery-interfaces/mailgun.md index db47b06..908efc6 100644 --- a/versioned_docs/version-stable/delivery-interfaces/mailgun.md +++ b/versioned_docs/version-stable/delivery-interfaces/mailgun.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Configure Mailgun API integration for reliable email delivery with built-in analytics and better deliverability. -keywords: [Mailgun integration, email API, transactional email, Anaphora Mailgun, email delivery] +keywords: [ Mailgun integration, email API, transactional email, Anaphora Mailgun, email delivery ] --- # Mailgun @@ -14,18 +14,17 @@ Send reports via the Mailgun email API. - No SMTP server to manage - Better deliverability tracking -- Built-in analytics +- Easy setup - Higher sending limits ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| API Key | Mailgun API key | Yes | -| Domain | Your Mailgun domain | Yes | -| From Address | Sender email | Yes | -| Region | US or EU | Yes | +| Field | Description | Required | +|-----------------|-------------------------------------------------------------------------|----------| +| Name | Interface identifier | Yes | +| Sender email | Use your MailGun domain with any name e.g. myname@my-mailgun-domain.com | Yes | +| Sender name | Use any name that should be displayed as sender | No | +| Mailgun API key | API authentication | Yes | ## Setup Steps @@ -34,20 +33,12 @@ Send reports via the Mailgun email API. 1. Log in to Mailgun 2. Navigate to **Settings** > **API Keys** 3. Copy your Private API Key -4. Note your sending domain - -### 2. Configure in Anaphora - -1. Go to **Settings** > **Delivery Interfaces** -2. Add new **Mailgun** interface -3. Enter API key and domain -4. Select region (US or EU) -5. Set from address -6. Test and save +4. Note your Mailgun sender domain (to use in sender email) ## Domain Verification Ensure your Mailgun domain is verified for best deliverability: + - Add DNS records as instructed by Mailgun - Verify SPF and DKIM are configured diff --git a/versioned_docs/version-stable/delivery-interfaces/s3.md b/versioned_docs/version-stable/delivery-interfaces/s3.md index b47001f..ad2c4ad 100644 --- a/versioned_docs/version-stable/delivery-interfaces/s3.md +++ b/versioned_docs/version-stable/delivery-interfaces/s3.md @@ -1,33 +1,34 @@ --- sidebar_position: 5 description: Archive reports to S3 object storage - AWS S3, MinIO, and S3-compatible storage for compliance and historical records. -keywords: [S3 archiving, AWS S3, MinIO, object storage, report archive, compliance storage] +keywords: [ S3 archiving, AWS S3, MinIO, object storage, report archive, compliance storage ] --- # S3 Object Storage -![S3 Object Storage delivery interface configuration showing access key, secret key, region, bucket name, and custom endpoint fields](images/s3.png) + Archive reports to S3-compatible object storage for long-term retention, compliance, and historical reference. +![S3 Object Storage delivery interface configuration showing access key, secret key, region, bucket name, and custom endpoint fields](images/s3.png) + ## Use Cases -| Scenario | Benefit | -|----------|---------| -| **Compliance archiving** | Immutable records for audit requirements | +| Scenario | Benefit | +|--------------------------|------------------------------------------------| +| **Compliance archiving** | Immutable records for audit requirements | | **Historical reference** | "What did this dashboard look like on date X?" | -| **Long-term retention** | Store beyond housekeeping limits | -| **Cross-system access** | Other tools can retrieve archived reports | +| **Long-term retention** | Store beyond housekeeping limits | +| **Cross-system access** | Other tools can retrieve archived reports | ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| **Name** | Interface identifier | Yes | -| **Type** | S3 Object Storage | Yes | -| **Access key ID** | AWS access key or S3-compatible credentials | Yes | -| **Secret access key** | AWS secret key (stored encrypted) | Yes | -| **Region** | AWS region (e.g., `eu-west-1`) | Yes | -| **Bucket name** | Target S3 bucket | Yes | -| **Custom endpoint** | For S3-compatible storage (MinIO, etc.) | No | +| Field | Description | Required | +|-----------------------|---------------------------------------------|----------| +| **Name** | Interface identifier | Yes | +| **Access key ID** | AWS access key or S3-compatible credentials | Yes | +| **Secret access key** | AWS secret key (stored encrypted) | Yes | +| **Region** | AWS region (e.g., `eu-west-1`) | Yes | +| **Bucket name** | Target S3 bucket | Yes | +| **Custom endpoint** | For S3-compatible storage (MinIO, etc.) | No | ## Provider Configurations @@ -71,38 +72,6 @@ Bucket name: your-bucket Custom endpoint: https://s3.us-west-002.backblazeb2.com ``` -## Path Organization - -Reports are stored with a configurable path structure. Configure the path prefix in the job's Delivery settings: - -``` -s3://my-reports-bucket/ -├── anaphora/ -│ ├── daily-dashboards/ -│ │ ├── 2025/ -│ │ │ ├── 01/ -│ │ │ │ ├── 2025-01-15-dashboard.pdf -│ │ │ │ └── 2025-01-16-dashboard.pdf -│ ├── compliance-reports/ -│ │ └── ... -│ └── alerts/ -│ └── ... -``` - -### Path Variables - -Use variables in the path prefix for automatic organization: - -| Variable | Description | Example | -|----------|-------------|---------| -| `{{year}}` | 4-digit year | `2025` | -| `{{month}}` | 2-digit month | `01` | -| `{{day}}` | 2-digit day | `15` | -| `{{job_name}}` | Job identifier | `daily-dashboard` | -| `{{date}}` | Full date | `2025-01-15` | - -**Example path prefix:** `anaphora/{{job_name}}/{{year}}/{{month}}/` - ## IAM Permissions For AWS S3, the IAM user/role needs these permissions: @@ -131,55 +100,21 @@ For AWS S3, the IAM user/role needs these permissions: For write-only archiving, you can remove `s3:GetObject` permission. ::: -## Lifecycle Policies - -Configure S3 lifecycle policies for automatic management: - -| Policy | Description | -|--------|-------------| -| **Transition to Glacier** | Move old reports to cheaper storage | -| **Expiration** | Auto-delete after retention period | -| **Versioning** | Keep multiple versions for compliance | - -### Example Lifecycle Rule (AWS) - -```json -{ - "Rules": [ - { - "ID": "ArchiveOldReports", - "Status": "Enabled", - "Filter": { "Prefix": "anaphora/" }, - "Transitions": [ - { - "Days": 90, - "StorageClass": "GLACIER" - } - ], - "Expiration": { - "Days": 365 - } - } - ] -} -``` - ## Testing 1. Configure the S3 interface with your credentials 2. Click **Test** 3. Verify a test file appears in your bucket -4. Check the file path matches your expectations ## Troubleshooting -| Issue | Solution | -|-------|----------| -| Access Denied | Verify IAM permissions, check bucket policy | -| Invalid credentials | Double-check access key and secret | -| Bucket not found | Verify bucket name and region match | -| Connection timeout | Check custom endpoint URL, verify network access | -| SSL certificate error | For self-signed certs, configure trust settings | +| Issue | Solution | +|-----------------------|--------------------------------------------------| +| Access Denied | Verify IAM permissions, check bucket policy | +| Invalid credentials | Double-check access key and secret | +| Bucket not found | Verify bucket name and region match | +| Connection timeout | Check custom endpoint URL, verify network access | +| SSL certificate error | For self-signed certs, configure trust settings | ## Best Practices @@ -188,18 +123,4 @@ Configure S3 lifecycle policies for automatic management: - Use dedicated IAM credentials with minimal permissions - Enable bucket versioning for compliance requirements - Consider enabling server-side encryption (SSE-S3 or SSE-KMS) -- Restrict bucket access with bucket policies - -### Organization - -- Use consistent path prefixes across jobs -- Include date components for easy browsing -- Separate compliance reports from operational reports -- Document your bucket structure - -### Cost Management - -- Configure lifecycle policies to transition old data to Glacier -- Set expiration for non-critical reports -- Monitor bucket size and request costs -- Consider S3 Intelligent-Tiering for variable access patterns +- Restrict bucket access with bucket policies \ No newline at end of file diff --git a/versioned_docs/version-stable/delivery-interfaces/slack.md b/versioned_docs/version-stable/delivery-interfaces/slack.md index 6ebe680..4b00de9 100644 --- a/versioned_docs/version-stable/delivery-interfaces/slack.md +++ b/versioned_docs/version-stable/delivery-interfaces/slack.md @@ -1,61 +1,30 @@ --- sidebar_position: 3 description: Configure Slack webhook integration to deliver Anaphora reports directly to Slack channels with rich formatting. -keywords: [Slack integration, webhook delivery, Slack notifications, report delivery, Anaphora Slack] +keywords: [ Slack integration, webhook delivery, Slack notifications, report delivery, Anaphora Slack ] --- # Slack -Deliver reports directly to Slack channels. - -## Configuration - -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| Webhook URL | Slack Incoming Webhook | Yes | -| Default Channel | Fallback channel | No | +Deliver reports directly to Slack channels. Use the webhook delivery interface to send Slack messages. ## Setup Steps -### 1. Create Slack App - -1. Go to [api.slack.com/apps](https://api.slack.com/apps) -2. Click **Create New App** -3. Choose **From scratch** -4. Name it "Anaphora" and select workspace +### 1. Create Slack Webhook -### 2. Enable Incoming Webhooks +1. Go to [Slack Docs](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) +2. Follow the instructions to create an **Incoming Webhook** -1. In app settings, go to **Incoming Webhooks** -2. Toggle **Activate Incoming Webhooks** on -3. Click **Add New Webhook to Workspace** -4. Select the default channel -5. Copy the Webhook URL +### 2. Configure in Anaphora -### 3. Configure in Anaphora - -1. Go to **Settings** > **Delivery Interfaces** -2. Add new **Slack** interface +1. Go to **Delivery Interfaces** +2. Add new **Webhook** interface 3. Paste the Webhook URL -4. Test and save - -## Message Formatting - -Reports sent to Slack include: -- Report title as header -- Thumbnail preview (if image) -- Download link for full PDF -- Key metrics (if extracted) - -## Multiple Channels - -Create separate interfaces for different channels, or override the channel per-job. - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Webhook invalid | Regenerate webhook URL | -| Channel not found | Verify channel exists and bot has access | -| Message too large | Reduce captured content size | +4. Set the method to **POST** and body type to **JSON** +5. Add the JSON body: + ```json + { + "text": "Hello, world." + } + ``` +6. Test and save diff --git a/versioned_docs/version-stable/delivery-interfaces/smtp.md b/versioned_docs/version-stable/delivery-interfaces/smtp.md index 2cddaf2..72ac868 100644 --- a/versioned_docs/version-stable/delivery-interfaces/smtp.md +++ b/versioned_docs/version-stable/delivery-interfaces/smtp.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Configure SMTP email delivery for Anaphora reports. Supports SSL, STARTTLS, and common providers like Gmail and Office 365. -keywords: [SMTP configuration, email delivery, SSL email, Gmail SMTP, Office 365 SMTP, Anaphora email] +keywords: [ SMTP configuration, email delivery, SSL email, Gmail SMTP, Office 365 SMTP, Anaphora email ] --- # SMTP @@ -12,15 +12,15 @@ Send reports via your own SMTP email server. Supports SSL, STARTLS, plain ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| Host | SMTP server hostname | Yes | -| Port | SMTP port (25, 465, 587) | Yes | -| Username | SMTP authentication user | Usually | -| Password | SMTP authentication password | Usually | -| From Address | Sender email address | Yes | -| TLS/SSL | Encryption mode | Recommended | +| Field | Description | Required | +|--------------|------------------------------|-------------| +| Name | Interface identifier | Yes | +| Host | SMTP server hostname | Yes | +| Port | SMTP port (25, 465, 587) | Yes | +| Username | SMTP authentication user | Usually | +| Password | SMTP authentication password | Usually | +| From Address | Sender email address | Yes | +| TLS/SSL | Encryption mode | Recommended | ## Common Configurations @@ -61,8 +61,8 @@ TLS: STARTTLS ## Troubleshooting -| Issue | Solution | -|-------|----------| -| Connection refused | Check firewall, verify port | +| Issue | Solution | +|-----------------------|-----------------------------------------| +| Connection refused | Check firewall, verify port | | Authentication failed | Verify credentials, check app passwords | -| TLS error | Try different TLS mode | +| TLS error | Try different TLS mode | diff --git a/versioned_docs/version-stable/delivery-interfaces/webhook.md b/versioned_docs/version-stable/delivery-interfaces/webhook.md index f4e6fdb..28a2b28 100644 --- a/versioned_docs/version-stable/delivery-interfaces/webhook.md +++ b/versioned_docs/version-stable/delivery-interfaces/webhook.md @@ -1,7 +1,7 @@ --- sidebar_position: 4 description: Configure webhook delivery to send Anaphora reports to custom HTTP endpoints. Integrate with any system via JSON payloads. -keywords: [webhook integration, HTTP delivery, API integration, custom notifications, automation, Anaphora webhook] +keywords: [ webhook integration, HTTP delivery, API integration, custom notifications, automation, Anaphora webhook ] --- # WebHook @@ -19,67 +19,53 @@ Send reports to custom HTTP endpoints for integration with any system. ## Configuration -| Field | Description | Required | -|-------|-------------|----------| -| Name | Interface identifier | Yes | -| URL | Endpoint URL | Yes | -| Method | HTTP method (POST/PUT) | Yes | -| Headers | Custom headers | No | -| Authentication | Basic/Bearer/None | No | +| Field | Description | Required | +|-----------|-------------------------|----------| +| Name | Interface identifier | Yes | +| URL | Endpoint URL | Yes | +| Method | HTTP method (POST/PUT) | Yes | +| Headers | Custom headers | No | +| Body type | JSON, form-data | Yes | +| JSON Body | Custom payload template | No | +| Form Data | Key-value pairs | No | ## Payload Format -Anaphora sends a JSON payload: +### JSON Template + +Define a JSON structure that works with your endpoint. Use the ```$MESSAGE``` variable as placeholder for the report +content. This variable will be replaced with the custom text that you define in the job's delivery settings. + +Example: ```json { - "job_name": "Daily Report", - "job_id": "abc123", - "timestamp": "2026-01-15T09:00:00Z", - "status": "success", - "report_url": "https://anaphora.example.com/reports/xyz", - "variables": { - "error_count": 42, - "alert_triggered": true - }, - "attachments": [ - { - "type": "pdf", - "url": "https://anaphora.example.com/files/report.pdf" - } - ] + "title": "Anaphora Report", + "content": "$MESSAGE" } ``` -## Custom Headers +### Form Data -Add headers for authentication or routing: +Send key-value pairs as form data. Use the ```$MESSAGE``` variable for the report content. + +Example: ``` -Authorization: Bearer your-token -X-Custom-Header: value -Content-Type: application/json +report_title=Anaphora Report +report_content=$MESSAGE ``` -## Authentication Options +### JSON in Job Delivery -| Type | Configuration | -|------|---------------| -| None | No authentication | -| Basic | Username and password | -| Bearer | Token in Authorization header | -| Custom | Via custom headers | +In this case the entire body is defined in the job's delivery settings. -## Testing - -1. Use a tool like [webhook.site](https://webhook.site) for testing -2. Configure the test URL in Anaphora -3. Send a test payload -4. Verify the payload structure meets your needs +## Custom Headers -## Error Handling +Add headers for authentication or routing: -Anaphora retries failed webhook deliveries: -- 3 retry attempts -- Exponential backoff -- Failures logged in job history +``` +Authorization: Bearer your-token +X-Custom-Header: value +Content-Type: application/json +``` diff --git a/versioned_docs/version-stable/getting-started/configuration.md b/versioned_docs/version-stable/getting-started/configuration.md index a35ba65..569c2b8 100644 --- a/versioned_docs/version-stable/getting-started/configuration.md +++ b/versioned_docs/version-stable/getting-started/configuration.md @@ -1,53 +1,25 @@ --- sidebar_position: 2 description: Configure Anaphora with environment variables for production deployments. PUBLIC_URL, admin credentials, and license setup. -keywords: [Anaphora configuration, environment variables, PUBLIC_URL, setup guide, production deployment] +keywords: [ Anaphora configuration, environment variables, PUBLIC_URL, setup guide, production deployment ] --- # Configuration Guide -Configure Anaphora for your environment and requirements. - -## Environment Variables - -Anaphora is configured via environment variables: - -| Variable | Description | Required | -|----------|-------------|----------| -| `PUBLIC_URL` | External URL where Anaphora is accessible | Yes (production) | -| `ADMIN_USERNAME` | Initial admin username | No (default: `admin`) | -| `ADMIN_PASSWORD` | Initial admin password | No (prompted on first login) | -| `ACTIVATION_KEY` | PRO/Enterprise activation key | No | -| `ANAPHORA_DATA_DIR` | Data storage path | No (default: `/data`) | - -### PUBLIC_URL - -The `PUBLIC_URL` environment variable defines the external URL where Anaphora is accessible. This is **required for production deployments** and used for: - -- SSO callback URLs (SAML, OIDC) -- Links in email notifications -- Webhook response URLs - -```bash -# Example: Production deployment -PUBLIC_URL=https://anaphora.company.com - -# Example: Local development (optional) -PUBLIC_URL=http://localhost:3000 -``` - -:::warning Required for SSO -If you're using SAML or OIDC authentication, `PUBLIC_URL` must be set correctly. The callback URLs registered with your identity provider must match this value. -::: +After installing Anaphora and setting it up with Environment variables, you can further configure it in the admin UI. ## Initial Setup On first launch: 1. Navigate to `PUBLIC_URL` in your browser -2. Log in with admin credentials (set via environment variables or prompted) -3. Configure your license if using PRO/Enterprise features -4. Create your first job +2. Create the initial admin user (if not set via env vars) +3. Log in with your admin credentials +4. Go to **Settings** → **System** to review and adjust global settings +5. Configure your license if using PRO/Enterprise features +6. Create your first job + + ## Next Steps diff --git a/versioned_docs/version-stable/getting-started/features.md b/versioned_docs/version-stable/getting-started/features.md index e9f0676..842a6cf 100644 --- a/versioned_docs/version-stable/getting-started/features.md +++ b/versioned_docs/version-stable/getting-started/features.md @@ -1,12 +1,13 @@ --- sidebar_position: 3 description: Compare Anaphora Free, PRO, and Enterprise editions. See what's included in each tier and choose the right plan for your reporting needs. -keywords: [Anaphora features, free edition, pro license, enterprise edition, activation key, feature comparison, pricing tiers] +keywords: [ Anaphora features, free edition, pro license, enterprise edition, activation key, feature comparison, pricing tiers ] --- # Features & Editions -Choose the edition that fits your needs. All editions include the **full reporting engine** — higher tiers unlock team features and integrations. +Choose the edition that fits your needs. All editions include the **full reporting engine** — higher tiers unlock team +features and integrations. :::info 🚀 Ready to try PRO or Enterprise? **[Get a free trial key →](https://portal.anaphora.it)** — No credit card required. Instant activation. @@ -17,13 +18,16 @@ Choose the edition that fits your needs. All editions include the **full reporti **Perfect for evaluation and personal projects** :::tip What you get + - ✅ Up to **2 scheduled jobs** - ✅ Kibana, Grafana, and generic web capture - ✅ PDF report composer with custom layouts -- ✅ Email (SMTP), Mailgun, Slack, and Webhook delivery +- ✅ Email (SMTP) delivery - ✅ Notification throttling and retry policies - ✅ Local user authentication -::: +- ✅ **Self-Monitoring API** — health endpoints for external systems +- ✅ **AI Analysis** — LLM-powered summaries and anomaly detection + ::: **Best for:** Trying Anaphora, personal dashboards, small-scale reporting @@ -34,11 +38,12 @@ Choose the edition that fits your needs. All editions include the **full reporti **For production teams who need unlimited jobs and AI** :::tip Everything in Free, plus + - ✅ **Unlimited jobs** — no restrictions +- ✅ **Additional Delivery** - Mailgun, Slack, Webhook, and S3 - ✅ **Spaces** — organize jobs into isolated workspaces -- ✅ **AI Analysis** — LLM-powered summaries and anomaly detection - ✅ **Priority support** — faster response times -::: + ::: **Best for:** Production workloads, growing teams, AI-enhanced reports @@ -49,11 +54,12 @@ Choose the edition that fits your needs. All editions include the **full reporti **For organizations requiring SSO and compliance** :::tip Everything in PRO, plus + - ✅ **LDAP / Active Directory** — enterprise directory auth - ✅ **SAML SSO** — Okta, Azure AD, OneLogin, etc. - ✅ **OpenID Connect** — Google, Auth0, Keycloak, etc. -- ✅ **S3 Archiving** — compliance-ready report storage -- ✅ **Self-Monitoring API** — health endpoints for external systems +- ✅ **Branding** — Customization of login screen + ::: **Best for:** Corporate SSO requirements, compliance, large-scale deployments @@ -62,36 +68,41 @@ Choose the edition that fits your needs. All editions include the **full reporti ## Feature Comparison -| Feature | 🆓 Free | ⭐ PRO | 🏢 Enterprise | -|---------|:-------:|:------:|:-------------:| -| **Jobs** | 2 | ∞ Unlimited | ∞ Unlimited | -| | | | | -| **Capture** | | | | -| Kibana Connector | ✅ | ✅ | ✅ | -| Grafana Connector | ✅ | ✅ | ✅ | -| Generic Web Capture | ✅ | ✅ | ✅ | -| PDF Composer | ✅ | ✅ | ✅ | -| | | | | -| **Delivery** | | | | -| Email (SMTP) | ✅ | ✅ | ✅ | -| Mailgun | ✅ | ✅ | ✅ | -| Slack | ✅ | ✅ | ✅ | -| Webhook | ✅ | ✅ | ✅ | -| S3 Archiving | ❌ | ❌ | ✅ | -| | | | | -| **Team & Organization** | | | | -| Spaces (Multi-tenancy) | ❌ | ✅ | ✅ | -| AI Analysis | ❌ | ✅ | ✅ | -| | | | | -| **Authentication** | | | | -| Local Users | ✅ | ✅ | ✅ | -| LDAP / Active Directory | ❌ | ❌ | ✅ | -| SAML SSO | ❌ | ❌ | ✅ | -| OpenID Connect | ❌ | ❌ | ✅ | -| | | | | -| **Operations** | | | | -| Self-Monitoring API | ❌ | ❌ | ✅ | -| Priority Support | ❌ | ✅ | ✅ | +| Feature | 🆓 Free | ⭐ PRO | 🏢 Enterprise | +|-------------------------|:-------:|:-----------:|:-------------:| +| **Jobs** | 2 | ∞ Unlimited | ∞ Unlimited | +| **Delivery Interfaces** | 2 | ∞ Unlimited | ∞ Unlimited | +| | | | | +| **Capture** | | | | +| Capture Actions | 3 | ∞ Unlimited | ∞ Unlimited | +| Kibana Connector | ✅ | ✅ | ✅ | +| Grafana Connector | ✅ | ✅ | ✅ | +| Generic Web Capture | ✅ | ✅ | ✅ | +| PDF Composer | ✅ | ✅ | ✅ | +| | | | | +| **Delivery** | | | | +| Email (SMTP) | ✅ | ✅ | ✅ | +| Mailgun | ❌ | ✅ | ✅ | +| Slack | ❌ | ✅ | ✅ | +| Webhook | ❌ | ✅ | ✅ | +| S3 Archiving | ❌ | ✅ | ✅ | +| | | | | +| **Team & Organization** | | | | +| AI Analysis | ✅ | ✅ | ✅ | +| Job Templates | ✅ | ✅ | ✅ | +| Advanced Job Templates | ❌ | ✅ | ✅ | +| Spaces (Multi-tenancy) | ❌ | ✅ | ✅ | +| Branding | ❌ | ❌ | ✅ | +| | | | | +| **Authentication** | | | | +| Local Users | ✅ | ✅ | ✅ | +| LDAP / Active Directory | ❌ | ❌ | ✅ | +| SAML SSO | ❌ | ❌ | ✅ | +| OpenID Connect | ❌ | ❌ | ✅ | +| | | | | +| **Operations** | | | | +| Self-Monitoring API | ✅ | ✅ | ✅ | +| Priority Support | ❌ | ✅ | ✅ | ## Activation Keys @@ -110,9 +121,12 @@ docker run -p 3000:3000 \ **Option 2: Admin UI** -1. Go to **Settings** → **License** -2. Enter your activation key -3. Click **Activate** +1. Go to **Settings** → **System** → **Activation Key** +2. Click on Load another +3. Enter your activation key +4. Click **Activate** + +![](images/activationkey.png) ### Key Benefits @@ -128,7 +142,7 @@ docker run -p 3000:3000 \ - Instant delivery — no waiting - Full access to all features - No credit card required -::: + ::: ## Need Help? diff --git a/versioned_docs/version-stable/getting-started/images/activationkey.png b/versioned_docs/version-stable/getting-started/images/activationkey.png new file mode 100644 index 0000000..b97f9c5 Binary files /dev/null and b/versioned_docs/version-stable/getting-started/images/activationkey.png differ diff --git a/versioned_docs/version-stable/getting-started/installation.md b/versioned_docs/version-stable/getting-started/installation.md index 6ca9e43..4f4b713 100644 --- a/versioned_docs/version-stable/getting-started/installation.md +++ b/versioned_docs/version-stable/getting-started/installation.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Install Anaphora with Docker or Docker Compose. Quick setup guide for automated Kibana and Grafana report generation. -keywords: [Anaphora installation, Docker setup, Kibana reporting tool, Grafana reporting tool, automated reports installation] +keywords: [ Anaphora installation, Docker setup, Kibana reporting tool, Grafana reporting tool, automated reports installation ] --- # Installation Guide @@ -11,7 +11,6 @@ Get Anaphora up and running in your environment. ## Requirements - Docker and Docker Compose (recommended) -- Or: Java 17+ runtime environment - Network access to your Kibana/Grafana instances ## Quick Start with Docker @@ -21,23 +20,27 @@ The fastest way to get started is using Docker: ```bash docker run -p 3000:3000 \ -e PUBLIC_URL=http://localhost:3000 \ - -e ADMIN_USERNAME=admin \ - -e ADMIN_PASSWORD=admin \ - -d beshu-tech/anaphora + -e DB_ENCRYPTION_KEY=your-encryption-key \ + -d beshultd/anaphora ``` Then open [http://localhost:3000](http://localhost:3000) in your browser and log in with `admin` / `admin`. ### Environment Variables -| Variable | Description | Example | -|----------|-------------|---------| -| `PUBLIC_URL` | External URL where Anaphora is accessible | `http://anaphora.example.com:3000` | -| `ADMIN_USERNAME` | Initial admin username | `admin` | -| `ADMIN_PASSWORD` | Initial admin password | `your-secure-password` | +| Variable | Description | Required | Example | +|---------------------|-------------------------------------------------|-------------|------------------------------------| +| `PUBLIC_URL` | External URL where Anaphora is accessible | Yes | `http://anaphora.example.com:3000` | +| `DB_ENCRYPTION_KEY` | Key used to encrypt the DB. | Recommended | `your-encryption-key` | +| `ADMIN_USERNAME` | Initial admin username | No | `admin` | +| `ADMIN_PASSWORD` | Initial admin password | No | `your-secure-password` | +| `ACTIVATION_KEY` | License / activation key for Anaphora | No | `xxxx-xxxx-xxxx-xxxx` | +| `DEBUG` | Enable debug logging | No | `false` | +| `WORKER_COUNT` | Number of concurrent Puppeteer worker instances | No | `2` | :::tip Production Deployment -For production, use a strong password and set `PUBLIC_URL` to your actual external URL (this is used for callback URLs in SSO configurations). +For production, use a strong `DB_ENCRYPTION_KEY` and set `PUBLIC_URL` to your actual external URL (this is used for +callback URLs in SSO configurations). ::: ### Docker Compose @@ -48,23 +51,29 @@ For production deployments, use Docker Compose with persistent storage: version: '3.8' services: anaphora: - image: beshu-tech/anaphora + image: beshultd/anaphora ports: - "3000:3000" volumes: - - anaphora-data:/data + - anaphora-storage:/usr/src/app/storage + - anaphora-content:/usr/src/app/content environment: - PUBLIC_URL=https://anaphora.example.com + - DB_ENCRYPTION_KEY=${DB_ENCRYPTION_KEY} - ADMIN_USERNAME=admin - ADMIN_PASSWORD=${ADMIN_PASSWORD} - ACTIVATION_KEY=${ACTIVATION_KEY} + - DEBUG=false + - WORKER_COUNT=2 volumes: - anaphora-data: + anaphora-storage: + anaphora-content: ``` :::tip 🎁 Get a Free Trial Key -The `ACTIVATION_KEY` unlocks PRO or Enterprise features. **[Request your free trial key →](https://portal.anaphora.it)** — instant activation, no credit card required. +The `ACTIVATION_KEY` unlocks PRO or Enterprise features. +**[Request your free trial key →](https://portal.anaphora.it)** — instant activation, no credit card required. ::: ## Need Help? diff --git a/versioned_docs/version-stable/jobs/capture.md b/versioned_docs/version-stable/jobs/capture.md index 549c191..c0bb366 100644 --- a/versioned_docs/version-stable/jobs/capture.md +++ b/versioned_docs/version-stable/jobs/capture.md @@ -1,29 +1,31 @@ --- sidebar_position: 2 description: Configure Anaphora capture settings - Kibana, Grafana, and generic web connectors with authentication and advanced multi-step workflows. -keywords: [Kibana capture, Grafana capture, headless browser, web scraping, dashboard capture, authentication] +keywords: [ Kibana capture, Grafana capture, headless browser, web scraping, dashboard capture, authentication ] --- # Capture Configuration -The Capture tab defines what data to collect and how. Anaphora's headless Chrome-based connector can navigate, authenticate, and capture any web application. +The Capture tab defines what data to collect and how. Anaphora's headless Chrome-based connector can navigate, +authenticate, and capture any web application. ## Capture Modes ### Basic Mode Simple single-URL capture: + 1. Select a connector (Kibana, Grafana, Generic URL) 2. Enter the URL -3. Configure authentication -4. Set time range (for dashboards) -5. Capture +3. Configure authentication (if needed) +4. Capture Best for: Quick dashboard snapshots, simple reports. ### Advanced Mode Multi-step browser automation: + 1. Chain multiple navigation and capture actions 2. Extract data into variables 3. Evaluate conditions @@ -35,19 +37,20 @@ Toggle **Advanced** to switch modes. ### Kibana Connector -When you paste a Kibana URL, Anaphora automatically recognizes it and provides Kibana-specific options. +Use the Kibana connector to use Anaphora's built-in support for Kibana pages. **Supported Page Types:** + - Dashboards - Canvas workpads - Discover views +**Authentication:** +Login to Kibana using the ReadonlyREST login access. + **Time Range Configuration:** -| Option | Description | -|--------|-------------| -| Absolute | Specific date/time range | -| Relative | "Last 24 hours", "Last 7 days", etc. | -| Dashboard default | Use time range saved in dashboard | +Either set the time range in the Kibana UI before copying the URL, or set it in Anaphora using a similar syntax to +Kibana's time picker. **Capture Options:** | Mode | Description | @@ -56,48 +59,36 @@ When you paste a Kibana URL, Anaphora automatically recognizes it and provides K | **Per visualization** | Separate snapshot for each panel | :::tip Per-Visualization Capture -Capturing each visualization separately gives you more control in the Composer — arrange panels in custom layouts, exclude certain visualizations, or combine with other content. +Capturing each visualization separately gives you more control in the Composer — arrange panels in custom layouts, +exclude certain visualizations, or combine with other content. ::: -**Authentication Methods:** - -| Method | Description | -|--------|-------------| -| None | Public dashboards | -| ReadonlyREST login | Username/password with ReadonlyREST | -| Enterprise login | SSO with tenancy support | -| API key | For headless access | - ### Grafana Connector -Captures Grafana dashboards via the Grafana API. +Use the Grafana connector to use Anaphora's built-in support for Grafana pages. -**Configuration:** -| Field | Description | -|-------|-------------| -| URL | Grafana dashboard URL | -| API Key | Service account token | -| Time Range | Override dashboard time settings | -| Kiosk Mode | Cleaner capture without UI chrome | +**Authentication:** +Login with a Grafana user. Works for Grafana Cloud and self-hosted Grafana instances. **Capture Options:** + - Full dashboard capture - Panel-level capture (similar to Kibana per-visualization) ### Generic Web Connector -For any authenticated web application — if a human can reach it, Anaphora can capture it. +For any web page — if a human can reach it, Anaphora can capture it. **Use Cases:** + - Internal tools and dashboards - SaaS applications - Custom web applications -- Pages requiring complex login flows **Authentication:** -- Form-based login (username/password) -- SSO redirect flows -- Multi-factor authentication (with manual setup) + +- Natively supports Basic Auth headers +- Use Advanced mode to script login flows ## Advanced Capture Workflows @@ -107,36 +98,36 @@ Advanced mode enables multi-step browser automation for complex scenarios. ```mermaid flowchart LR - A["Navigate to URL"] --> B["Authenticate (if needed)"] + A["Navigate to URL"]] B --> C["Interact (click, type)"] C --> D["Capture (snapshot to var)"] ``` ### Browser Actions -| Action | Description | Example | -|--------|-------------|---------| -| **Navigate** | Go to a URL | Open dashboard | -| **Click** | Click an element | Expand menu, select filter | -| **Type** | Enter text | Search box, form field | +| Action | Description | Example | +|----------------------|------------------|----------------------------| +| **Navigate** | Go to a URL | Open dashboard | +| **Click** | Click an element | Expand menu, select filter | +| **Type** | Enter text | Search box, form field | | **Wait for visible** | Wait for element | Dashboard loading complete | -| **Wait** | Pause execution | Allow animations to finish | -| **Reload** | Refresh page | Clear cached state | +| **Wait** | Pause execution | Allow animations to finish | +| **Reload** | Refresh page | Clear cached state | ### Data Extraction Actions -| Action | Description | Example | -|--------|-------------|---------| -| **Capture value** | Extract text into variable | Error count, status text | -| **Capture snapshot** | Screenshot element to variable | Chart, panel, full page | -| **Calculate** | Arithmetic on variables | `$errors / $total * 100` | +| Action | Description | Example | +|----------------------|--------------------------------|--------------------------| +| **Capture value** | Extract text into variable | Error count, status text | +| **Capture snapshot** | Screenshot element to variable | Chart, panel, full page | +| **Calculate** | Arithmetic on variables | `errors / total * 100` | ### Control Flow Actions -| Action | Description | Example | -|--------|-------------|---------| -| **Conditional block** | If/else logic | Only notify if errors > 0 | -| **Break** | Stop without sending | Skip report if threshold not met | +| Action | Description | Example | +|-----------------------|----------------------|----------------------------------| +| **Conditional block** | If/else logic | Only notify if errors > 0 | +| **Break** | Stop without sending | Skip report if threshold not met | ### Example: Multi-Source Report @@ -144,16 +135,15 @@ Capture from multiple dashboards in one job: ``` 1. Navigate → Kibana Dashboard A -2. Capture snapshot → $dashboard_a +2. Capture snapshot → dashboard_a 3. Navigate → Grafana Dashboard B -4. Capture snapshot → $dashboard_b +4. Capture snapshot → dashboard_b 5. Navigate → Internal Tool 6. Click → "Generate Report" button -7. Wait for visible → Report table -8. Capture snapshot → $internal_report +7. Capture snapshot → internal_report ``` -Result: Three snapshots available in Composer as `$dashboard_a`, `$dashboard_b`, `$internal_report`. +Result: Three snapshots available in Composer as `dashboard_a`, `dashboard_b`, `internal_report`. ### Example: Conditional Alert @@ -161,13 +151,11 @@ Only send notification when error threshold is exceeded: ``` 1. Navigate → Error Dashboard -2. Capture value → $error_count (from error counter element) -3. Calculate → $threshold = 100 -4. Conditional block: - - If $error_count > $threshold: - - Capture snapshot → $alert_screenshot - - Else: +2. Capture value → error_count (from error counter element) +3. Conditional block: + - If error_count < 100: - Break (no notification sent) +4. Capture snapshot → error_dashboard ``` ## Authentication Best Practices @@ -175,20 +163,14 @@ Only send notification when error threshold is exceeded: ### Service Accounts For production jobs: + - Create dedicated service accounts with read-only access -- Use API keys where available (more stable than login flows) - Store credentials securely in Anaphora's encrypted database -### Handling SSO - -For complex SSO flows: -1. Use Advanced mode to manually navigate the login process -2. Add Wait actions between authentication steps -3. Test thoroughly — SSO flows can be timing-sensitive - ### Kibana with ReadonlyREST Anaphora has first-class support for ReadonlyREST authentication: + - Simple username/password login - Tenancy selection for multi-tenant Kibana - Enterprise SSO integration @@ -198,20 +180,21 @@ Anaphora has first-class support for ReadonlyREST authentication: ### Stable Captures For reliable automation: + - Use stable dashboard URLs (avoid temporary/session-based URLs) - Prefer consistent layouts — dynamic dashboards may produce varying results -- Add explicit Wait actions after navigation -- Use element-specific captures rather than full-page when possible +- Add wait actions when necessary to ensure content is fully loaded +- If possible use element-specific captures rather than full-page when possible ### Handling Failures - Configure retry policies in General tab -- Use Wait for visible before captures - Test captures manually before scheduling ## Testing Click **Test capture** to: + 1. Run the capture workflow immediately 2. Preview all captured snapshots 3. Verify authentication works @@ -219,7 +202,8 @@ Click **Test capture** to: 5. Debug any issues :::tip Debug Workflow -Use Test frequently while building Advanced workflows. Each action's result is visible, making it easy to identify where issues occur. +Use Test frequently while building Advanced workflows. Each action's result is visible, making it easy to identify where +issues occur. ::: ## Next Steps diff --git a/versioned_docs/version-stable/jobs/composer.md b/versioned_docs/version-stable/jobs/composer.md index 29da1ee..8bada95 100644 --- a/versioned_docs/version-stable/jobs/composer.md +++ b/versioned_docs/version-stable/jobs/composer.md @@ -1,253 +1,41 @@ --- sidebar_position: 3 description: Design professional PDF reports with Anaphora's block-based composer - layouts, branding, snapshots, and AI-generated content. -keywords: [PDF report builder, report composer, branded reports, PDF layout, report template] +keywords: [ PDF report builder, report composer, branded reports, PDF layout, report template ] --- # Composer - Report Builder -The Composer tab is where captured content becomes a professional report. Using a block-based editor, you can create branded PDFs with custom layouts, text, images, and snapshots. - -## Overview - -After capture, the Composer assembles your content into a deliverable format: - -```mermaid -flowchart TB - subgraph page["Report Page"] - header["**Header**
Logo | Title | Date"] - snapshots["**Snapshots**
$dashboard_a | $dashboard_b"] - ai["**AI Analysis**
$ai_summary"] - footer["**Footer**
Page 1 of 2"] - - header --> snapshots --> ai --> footer - end -``` +The Composer tab is where captured content becomes a professional report. Using a block-based editor, you can create +branded PDFs with custom layouts, text, images, and snapshots. ## Block Types -### Content Blocks - -| Block | Description | -|-------|-------------| -| **Snapshot** | Insert captured screenshot (from variable) | -| **Text** | Headings, paragraphs, metadata | -| **Image** | Logos, icons, decorative images | -| **AI Content** | AI-generated analysis or summary | - -### Layout Blocks - -| Block | Description | -|-------|-------------| -| **Columns** | Multi-column layouts (2, 3, or custom) | -| **Divider** | Horizontal line separator | -| **Spacer** | Vertical whitespace | -| **Page Break** | Force new page | - -### Structure Blocks - -| Block | Description | -|-------|-------------| -| **Header** | Repeating page header | -| **Footer** | Repeating page footer | -| **Container** | Grouping with background/border | - -## Block Editor - -### Adding Blocks - -1. Click **+ Add Block** or use the block palette -2. Select block type -3. Configure block properties -4. Drag to reposition - -### Block Properties - -Each block has configurable properties: - -**Text Block Properties:** -| Property | Options | -|----------|---------| -| Content | Text with variable support | -| Heading Level | H1, H2, H3, paragraph | -| Alignment | Left, center, right | -| Font Size | Custom or preset sizes | -| Color | Text color picker | - -**Snapshot Block Properties:** -| Property | Options | -|----------|---------| -| Variable | Select from captured snapshots | -| Size | Width/height or auto | -| Border | None, thin, medium | -| Caption | Optional text below image | - -**Container Properties:** -| Property | Options | -|----------|---------| -| Background | Color or image | -| Padding | Inner spacing | -| Border | Style, color, radius | -| Opacity | Transparency level | - -## Branding & Styling - -### Global Styles - -Set default styles for the entire report: - -| Setting | Description | -|---------|-------------| -| **Page Size** | A4, Letter, or custom dimensions | -| **Margins** | Top, bottom, left, right spacing | -| **Font Family** | Default typeface | -| **Colors** | Primary, secondary, accent colors | - -### Branded Reports - -Create professional branded reports: - -1. **Logo placement** — Header, footer, or watermark -2. **Color scheme** — Match corporate brand colors -3. **Typography** — Use brand-approved fonts -4. **Backgrounds** — Subtle patterns or gradients - -### Example: Corporate Template - -``` -Header: -├── Logo (left) -├── Report Title (center) -└── Date (right) - -Body: -├── Executive Summary (text) -├── Dashboard Snapshot (full width) -├── Two-Column Layout: -│ ├── Metrics Panel (left) -│ └── Trend Chart (right) -└── AI Analysis (text) - -Footer: -├── Company Name (left) -├── Page Number (center) -└── Confidentiality Notice (right) -``` - -## Template Variables - -Insert dynamic content using variables: - -### System Variables - -| Variable | Description | Example Output | -|----------|-------------|----------------| -| `{{date}}` | Report date | "January 15, 2025" | -| `{{time}}` | Report time | "09:30 AM" | -| `{{datetime}}` | Full timestamp | "2025-01-15 09:30:00" | -| `{{job_name}}` | Job name | "Daily Dashboard Report" | -| `{{job_id}}` | Job identifier | "job-123abc" | - -### Captured Variables - -Variables from the Capture workflow: - -| Syntax | Description | -|--------|-------------| -| `{{$snapshot_name}}` | Insert captured snapshot | -| `{{$value_name}}` | Insert captured text value | -| `{{$calculated}}` | Insert calculated result | - -### AI Variables - -When using AI providers: - -| Variable | Description | -|----------|-------------| -| `{{$ai_summary}}` | AI-generated summary | -| `{{$ai_analysis}}` | AI analysis of captured data | - -## Multi-Page Reports - -### Page Management - -- **Add Page** — Create additional pages -- **Page Order** — Drag pages to reorder -- **Page Break** — Force content to next page -- **Continuous** — Let content flow naturally - -### Page-Specific Content - -Each page can have: -- Different layouts -- Unique content blocks -- Shared headers/footers (optional) - -## Output Formats - -| Format | Use Case | Notes | -|--------|----------|-------| -| **PDF** | Email attachments, archival | Most common, best quality | -| **PNG** | Slack, chat apps | Single image, limited pages | -| **JPEG** | Smaller file size | Compressed, some quality loss | -| **HTML** | Web viewing | Interactive, larger file | - -## Templates - -### Saving Templates - -Save your composition as a reusable template: - -1. Design your report layout -2. Click **Save as Template** -3. Name and categorize -4. Reuse across jobs - -### Template Library - -- **Default templates** — Pre-built layouts -- **Custom templates** — Your saved designs -- **Shared templates** — Available within your Space - -## Preview & Testing - -### Preview Mode - -Click **Preview** to see the final rendered report: -- Actual PDF rendering -- Variable substitution -- Page breaks and layout -- Real captured content (if available) - -### Test Run - -For complete validation: -1. Run a test capture from Capture tab -2. Switch to Composer -3. Preview with actual data -4. Adjust layout as needed - -## Best Practices +### Capture Blocks -### Layout Tips +| Block | Description | +|---------------|-----------------------------------------------| +| **Snapshots** | All captured screenshots | +| **Variables** | Captured texts, calculated values, AI results | -- Use consistent margins and spacing -- Keep important content above the fold on page 1 -- Use page breaks to control pagination -- Test with different data volumes +### Component Blocks -### Performance +| Block | Description | +|-------------|----------------------------------------------------| +| **Text** | Add any text to the report. Can contain variables. | +| **Image** | Upload static images like logos | +| **Divider** | Horizontal line separator | +| **Spacer** | Vertical whitespace | -- Optimize image sizes before upload -- Limit complex layouts on high-frequency jobs -- Use appropriate output format for delivery channel +## Layout -### Accessibility +The report layout is built using a hierarchical structure of pages, rows, and cells. -- Use sufficient color contrast -- Include alt text for images -- Maintain readable font sizes -- Use clear heading hierarchy +| Structure | Description | +|-----------|---------------------------------------------------------------| +| **Page** | Pages reflect PDF pagination. Every page consists of rows. | +| **Row** | Rows split pages horizontally into sections. | +| **Cell** | Cells hold blocks within rows. Up to 3 cells can fit per row. | ## Next Steps diff --git a/versioned_docs/version-stable/jobs/delivery.md b/versioned_docs/version-stable/jobs/delivery.md index ef278e9..3a8962a 100644 --- a/versioned_docs/version-stable/jobs/delivery.md +++ b/versioned_docs/version-stable/jobs/delivery.md @@ -1,12 +1,13 @@ --- sidebar_position: 4 -description: Configure report delivery - email, Slack, webhooks, and S3 archiving. Multi-channel distribution and conditional routing. -keywords: [report delivery, email reports, Slack notifications, webhook, S3 archiving, report distribution] +description: Configure report delivery - email, webhooks, and S3 archiving. Multi-channel distribution and conditional routing. +keywords: [ report delivery, email reports, webhook, S3 archiving, report distribution ] --- # Delivery Configuration -The Delivery tab configures where and how reports are sent. Anaphora supports multi-channel delivery with conditional routing. +The Delivery tab configures where and how reports are sent. Anaphora supports multi-channel delivery via email, +webhooks, and S3 archiving. ## Overview @@ -18,7 +19,6 @@ flowchart LR subgraph channels["Delivery Channels"] email["Email"] - slack["Slack"] s3["S3"] webhook["Webhook"] end @@ -28,24 +28,23 @@ flowchart LR ## Delivery Interfaces -Delivery Interfaces are reusable destination configurations. Configure them once in Settings, then select them in any job. +Delivery Interfaces are reusable destination configurations. Configure them once in Settings, then select them in any +job. ### Available Types -| Interface | Best For | Features | -|-----------|----------|----------| -| **SMTP** | Corporate email | SSL/TLS, attachments | -| **Mailgun** | High-volume email | API-based, reliable | -| **Slack** | Team notifications | Channels, threads, images | -| **Webhook** | Integrations | Custom payloads, any endpoint | -| **S3** | Archival, compliance | Historical records, versioning | +| Interface | Best For | Features | +|-------------|----------------------|--------------------------------| +| **SMTP** | Corporate email | SSL/TLS, attachments | +| **Mailgun** | Transactional email | High volume, tracking | +| **Webhook** | Integrations | Custom payloads, any endpoint | +| **S3** | Archival, compliance | Historical records, versioning | ### Reusability You can configure multiple interfaces of each type: - Different SMTP servers for different teams -- Multiple Slack workspaces - Separate S3 buckets for different retention periods - Various webhooks for different integrations @@ -55,139 +54,49 @@ S3 is particularly valuable for historical archives and compliance workflows. ### Use Cases -| Scenario | Benefit | -|----------|---------| -| **Historical reference** | "What did this dashboard look like on date X?" | -| **Compliance evidence** | Immutable records for audit requirements | -| **Long-term retention** | Store reports beyond housekeeping limits | -| **Cross-system integration** | Other tools can access archived reports | - -### Configuration - -| Setting | Description | -|---------|-------------| -| Bucket | S3 bucket name | -| Region | AWS region | -| Path prefix | Folder structure for organization | -| Credentials | AWS access key or IAM role | - -### Organization Strategy - -Structure your S3 archive for easy retrieval: - -``` -s3://company-reports/ -├── anaphora/ -│ ├── daily-dashboards/ -│ │ ├── 2025/ -│ │ │ ├── 01/ -│ │ │ │ ├── 2025-01-15-dashboard.pdf -│ │ │ │ └── 2025-01-16-dashboard.pdf -│ ├── compliance-reports/ -│ │ └── ... -│ └── alerts/ -│ └── ... -``` +| Scenario | Benefit | +|------------------------------|------------------------------------------------| +| **Historical reference** | "What did this dashboard look like on date X?" | +| **Compliance evidence** | Immutable records for audit requirements | +| **Long-term retention** | Store reports beyond housekeeping limits | +| **Cross-system integration** | Other tools can access archived reports | ## Email Delivery -### SMTP Configuration - -| Setting | Description | -|---------|-------------| -| Host | SMTP server address | -| Port | Usually 587 (TLS) or 465 (SSL) | -| Security | None, SSL, or StartTLS | -| Authentication | Username/password | +Anaphora supports sending reports via SMTP or Mailgun. ### Email Options -| Field | Description | Supports Variables | -|-------|-------------|-------------------| -| From | Sender address | No | -| To | Recipients (comma-separated) | Yes | -| CC/BCC | Additional recipients | Yes | -| Subject | Email subject line | Yes | -| Body | Message content | Yes | -| Attachment | Include PDF report | - | - -### Example Subject Lines - -``` -Daily Dashboard Report - {{date}} -[ALERT] Error threshold exceeded - {{$error_count}} errors -Weekly Summary: {{job_name}} -``` - -## Slack Delivery - -### Slack Configuration - -| Setting | Description | -|---------|-------------| -| Workspace | Connected Slack workspace | -| Channel | Default destination channel | -| Thread | Reply to thread (optional) | - -### Message Options +| Field | Description | +|------------------|------------------------------------------------| +| Attachments | Whether to attach the PDF report to the email. | +| Message template | Customizable email body with variables. | +| Recipients | List of email addresses to send the report to. | -| Field | Description | -|-------|-------------| -| Channel | Override default channel | -| Message | Text message (supports Slack formatting) | -| Image | Embed report as image | -| PDF | Upload PDF as file | - -### Slack Formatting - -Use Slack's mrkdwn formatting: - -``` -*Daily Report* for {{date}} - -Dashboard shows {{$metric_count}} active users. - -See attached PDF for full details. -``` +:::tip Recipients +Recipient email addresses can be either marked as single user or as group address. Emails sent to single user addresses +will include a snooze and unsubscribe link in the footer. Group addresses will not include these links. +::: ## Webhook Delivery +Webhooks enable custom integrations with any HTTP endpoint. + ### Webhook Configuration -| Setting | Description | -|---------|-------------| -| URL | Endpoint to receive report | -| Method | POST (default) or PUT | -| Headers | Custom headers (auth, content-type) | -| Payload format | JSON, form-data, or raw | - -### Payload Structure - -Webhook payloads include: - -```json -{ - "job_name": "Daily Dashboard Report", - "job_id": "job-123abc", - "run_id": "run-456def", - "timestamp": "2025-01-15T09:30:00Z", - "status": "success", - "report_url": "https://anaphora.example.com/reports/...", - "variables": { - "$error_count": 42, - "$status": "warning" - } -} -``` +| Field | Description | +|--------------------|-----------------------------------------------------------------------------------------------| +| Message template | Customizable message body with variables. | +| JSON body template | Define the JSON payload with variables. Only available when enabled in the Webhook interface. | ### Webhook Use Cases -| Integration | Description | -|-------------|-------------| -| **Ticketing systems** | Create tickets for alerts | -| **Chat platforms** | Custom integrations beyond Slack | -| **Data pipelines** | Feed report data to analytics | -| **Custom dashboards** | Update external status pages | +| Integration | Description | +|-----------------------|----------------------------------------| +| **Ticketing systems** | Create tickets for alerts | +| **Chat platforms** | Create messages in collaboration tools | +| **Data pipelines** | Feed report data to analytics | +| **Custom dashboards** | Update external status pages | ## Multi-Channel Delivery @@ -203,93 +112,23 @@ Send the same report to multiple destinations: ### Example: Alert with Archive ``` -Delivery 1: Slack (immediate notification) +Delivery 1: Webhook e.g. Slack (immediate notification) Delivery 2: Email (stakeholder distribution) Delivery 3: S3 (permanent archive) ``` -## Conditional Delivery - -Combine with Advanced Capture to route reports based on conditions. - -### Routing by Severity - -``` -If $error_count > 100: - → Deliver to #critical-alerts (Slack) - → Deliver to oncall@company.com (Email) -Else if $error_count > 10: - → Deliver to #team-alerts (Slack) -Else: - → Archive only (S3) -``` - -### Routing by Content - -``` -If $region == "EMEA": - → Deliver to emea-team@company.com -Else if $region == "APAC": - → Deliver to apac-team@company.com -``` - -## Delivery Failure Handling - -### Retry Behavior - -If delivery fails: -1. Anaphora retries based on job retry policy -2. Failed deliveries are logged -3. Admin notification on persistent failures - ### Partial Success With multi-channel delivery: + - Each channel is attempted independently - Partial success (some channels succeed, others fail) is logged -- Successful deliveries are not re-attempted on retry ## Testing Delivery -### Test Run - -1. Click **Test** on the job -2. Run captures and compose -3. Deliver to configured channels -4. Verify receipt and formatting - -### Delivery Log - -Check delivery status in the Run log: -- Success/failure per channel -- Error messages for failures -- Timing information - -## Best Practices - -### Email - -- Use distribution lists for team delivery -- Test subject lines with variables -- Consider time zones for delivery timing - -### Slack - -- Use dedicated channels for automated reports -- Include context in messages (what, when, why) -- Consider thread replies for high-frequency alerts - -### S3 - -- Implement lifecycle policies in AWS for old files -- Use consistent naming conventions -- Enable versioning for compliance requirements - -### Webhooks - -- Implement retry/idempotency on receiving end -- Use authentication headers for security -- Log incoming webhooks for debugging +Every delivery config includes a **Test** button. Use it to verify configuration before saving the job. +All steps during the capture and delivery process are logged for troubleshooting. +Use debug mode to also receive a video of the capture process. ## Next Steps diff --git a/versioned_docs/version-stable/jobs/general.md b/versioned_docs/version-stable/jobs/general.md index cfa93b3..4db3145 100644 --- a/versioned_docs/version-stable/jobs/general.md +++ b/versioned_docs/version-stable/jobs/general.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Configure job scheduling, notification throttling, retry policies, and data retention settings in Anaphora. -keywords: [job scheduling, CRON, notification throttling, retry policy, housekeeping, data retention] +keywords: [ job scheduling, CRON, notification throttling, retry policy, housekeeping, data retention ] --- # General Settings @@ -10,44 +10,38 @@ The General tab defines how often a job runs, how noisy it is allowed to be, and ## Configuration Fields -| Field | Description | Required | -|-------|-------------|----------| -| Name | Job identifier shown in lists and reports | Yes | -| Description | Notes about the job's purpose | No | -| Frequency | How often to run (simple or CRON) | Yes | -| Max Notify Frequency | Minimum time between notifications | No | -| Retry Policy | Behavior on capture failures | No | -| Housekeeping | Automatic cleanup of old runs/reports | No | +| Field | Description | Required | +|----------------------|-------------------------------------------|----------| +| Name | Job identifier shown in lists and reports | Yes | +| Description | Notes about the job's purpose | No | +| Frequency | How often to run (simple or CRON) | Yes | +| Max Notify Frequency | Minimum time between notifications | No | +| Retry Policy | Behavior on capture failures | No | +| Housekeeping | Automatic cleanup of old runs/reports | No | ## Scheduling ### Simple Frequency -Set how often the job should run using natural intervals: - -| Interval | Example Use Case | -|----------|------------------| -| Every X minutes | High-frequency alerting (5-10 min) | -| Every X hours | Regular status checks | -| Every X days | Daily reports | -| Every X weeks | Weekly summaries | +Set how often the job should run using natural intervals. ### Advanced (CRON) Toggle **Advanced** to use CRON expressions for precise scheduling: -| CRON Expression | Description | -|-----------------|-------------| -| `0 9 * * *` | Every day at 9:00 AM | -| `0 */2 * * *` | Every 2 hours | -| `0 9 * * 1-5` | Weekdays at 9:00 AM | -| `0 0 1 * *` | First day of every month | -| `*/10 * * * *` | Every 10 minutes | -| `0 9,17 * * *` | At 9:00 AM and 5:00 PM | +| CRON Expression | Description | +|-----------------|--------------------------| +| `0 9 * * *` | Every day at 9:00 AM | +| `0 */2 * * *` | Every 2 hours | +| `0 9 * * 1-5` | Weekdays at 9:00 AM | +| `0 0 1 * *` | First day of every month | +| `*/10 * * * *` | Every 10 minutes | +| `0 9,17 * * *` | At 9:00 AM and 5:00 PM | ## Notification Throttling -**Max Notify Frequency** controls the maximum notification rate regardless of how often the job runs. This is especially important for high-frequency alerting jobs. +**Max Notify Frequency** controls the maximum notification rate regardless of how often the job runs. This is especially +important for high-frequency alerting jobs. ### Why Throttling Matters @@ -78,82 +72,39 @@ flowchart TD ### Example Configuration -| Job Frequency | Throttling | Result | -|---------------|------------|--------| -| Every 5 minutes | 3 hours | Max 8 notifications/day | -| Every 10 minutes | 1 hour | Max 24 notifications/day | -| Every hour | 6 hours | Max 4 notifications/day | -| Daily | None | 1 notification/day | +| Job Frequency | Throttling | Result | +|------------------|------------|--------------------------| +| Every 5 minutes | 3 hours | Max 8 notifications/day | +| Every 10 minutes | 1 hour | Max 24 notifications/day | +| Every hour | 6 hours | Max 4 notifications/day | +| Daily | None | 1 notification/day | :::tip Alerting Pattern High-frequency sampling + throttling creates an alerting-style workflow: + - Job runs every 5 minutes to detect issues quickly - Throttling prevents notification fatigue - Recipients get timely alerts without spam -::: + ::: ## Retry Policy -Configure how Anaphora handles failed captures: - -| Setting | Description | -|---------|-------------| -| **Retry Count** | Number of retry attempts before giving up | -| **Retry Delay** | Wait time between retries | -| **Suspend on Failure** | Disable job after X consecutive failures | - -### Example: Resilient Configuration - -``` -Retry Count: 3 -Retry Delay: 30 seconds -Suspend After: 5 consecutive failures -``` - -This configuration: -1. Retries a failed capture up to 3 times -2. Waits 30 seconds between attempts -3. Suspends the job if 5 runs in a row fail (prevents endless failures) - -### Failure Notifications - -When failures occur: -- Admin receives notification based on retry/suspend settings -- Failed runs are logged with error details -- Job can be manually re-enabled after fixing issues +Enable retries to retry failed runs automatically after failures. +When enabled, set how many times the run should be retried before giving up. ## Housekeeping (Data Retention) -Control automatic deletion of old data to manage storage: - -| Setting | Description | Example | -|---------|-------------|---------| -| **Run History** | How long to keep execution logs | 30 days | -| **Reports** | How long to keep generated PDFs | 90 days | -| **Artifacts** | How long to keep captures/snapshots | 7 days | - -### Retention Strategies - -| Job Type | Recommended Retention | -|----------|----------------------| -| Alerting (high-frequency) | Short: 7-14 days | -| Daily reports | Medium: 30-60 days | -| Compliance reports | Long: 1+ year | -| Development/testing | Minimal: 1-7 days | +Enable run expire time to automatically delete old runs and reports after a specified period. +This helps manage storage usage over time. :::warning Storage Impact High-frequency jobs generate more data. Without housekeeping: + - 10-minute job = 144 runs/day = 4,320 runs/month - Each run may include snapshots and reports - Storage can grow rapidly without retention limits ::: -### Per-Job vs Global Housekeeping - -- **Per-Job**: Configure in the General tab for job-specific retention -- **Global**: Set system-wide defaults in Administration settings -- Per-job settings override global defaults - ## Best Practices ### For Scheduled Reports @@ -170,7 +121,7 @@ Housekeeping: 90 days ```yaml Frequency: Every 5-10 minutes Throttling: 1-3 hours (balance speed vs. noise) -Retry: 2 attempts (fail fast) +Retry: Job runs often enough; retries usually not needed Housekeeping: 14 days (less storage needed) ``` @@ -180,7 +131,7 @@ Housekeeping: 14 days (less storage needed) Frequency: Weekly or monthly Throttling: None Retry: 5 attempts (ensure success) -Housekeeping: 365+ days (or use S3 archiving) +Housekeeping: Never ``` ## Next Steps diff --git a/versioned_docs/version-stable/jobs/index.md b/versioned_docs/version-stable/jobs/index.md index 0295eca..5cebfa2 100644 --- a/versioned_docs/version-stable/jobs/index.md +++ b/versioned_docs/version-stable/jobs/index.md @@ -84,7 +84,7 @@ Capture Dashboard -> Send to AI -> Receive Analysis -> Include in Report - **Visual Analysis** - Pass screenshots to AI models to evaluate dashboard content - **Text Summaries** - AI generates human-readable summaries of complex data - **Anomaly Detection** - AI identifies unusual patterns or concerning trends -- **DeepSeek Compatible** - Works with any AI provider using the DeepSeek API format +- **OpenAI Compatible** - Works with any AI provider using the OpenAI API format ## Visual Composer diff --git a/versioned_sidebars/version-stable-sidebars.json b/versioned_sidebars/version-stable-sidebars.json index 50594a3..4b1ee49 100644 --- a/versioned_sidebars/version-stable-sidebars.json +++ b/versioned_sidebars/version-stable-sidebars.json @@ -23,7 +23,7 @@ "items": [ "basic-examples/kibana-dashboard-report", "basic-examples/kibana-alert", - "basic-examples/conditional-report", + "basic-examples/kibana-conditional-report", "basic-examples/grafana-dashboard-report" ] }, @@ -36,9 +36,8 @@ }, "items": [ "advanced-examples/mixed-sources-report", - "advanced-examples/kibana-statistical-alert", - "advanced-examples/ai-news-collation", - "advanced-examples/branded-reports" + "advanced-examples/kibana-anomaly-alert", + "advanced-examples/ai-news-collation" ] }, {