The Aspects Plugin for Tutor
Aspects Learner Analytics integrates several open-source tools to add powerful analytics and reporting capabilities to the Open edX platform. This plugin enables seamless installation, configuration, and deployment of these tools via Tutor. The tools integrated by Aspects are:
ClickHouse: A fast and scalable analytics database.
Apache Superset: A data visualization and exploration platform.
OpenFUN Ralph: A Learning Record Store that validates and stores xAPI statements in ClickHouse.
Vector: A tool for forwarding logs and xAPI data to ClickHouse.
Event-Routing-Backends: An Open edX plugin that transforms tracking logs into xAPI and forwards them to Learning Record Stores in near real-time.
dbt: A SQL-based data pipeline builder, utilizing the aspects-dbt project.
For more information, refer to the Aspects architecture documentation.
Key Features
Streamlined deployment of analytics and reporting tools.
Integration with Open edX for real-time and historical data analytics.
Extensible architecture supporting customization.
Open edX Teak or higher: In-context metrics in Studio.
Compatibility
Current versions of the plugin are compatible with Tutor 19.0.0 and later and support Open edX releases from Sumac onward. Older releases can support Open edX versions as far back as Nutmeg. Details are available in the Aspects Documentation.
Breaking Changes
As of Aspects V4 the default data pipeline has changed from Ralph to Vector. This change improves performance and simplifies the architecture by eliminating the need to scale multiple Ralph containers and Celery workers for high-throughput scenarios.
Key changes:
Vector is now the default for xAPI event ingestion
The ASPECTS_VECTOR_RAW_XAPI_TABLE setting has been replaced with ASPECTS_RAW_XAPI_TABLE
The default database has changed from xapi (Ralph) to openedx (Vector)
To keep using Ralph as your data pipeline:
tutor config save --set ASPECTS_XAPI_SOURCE=ralph
tutor config save --set RUN_RALPH=True
tutor config save --set RUN_VECTOR=FalseThis will configure Aspects to use Ralph with the xapi database, preserving your existing data.
If you have customized ASPECTS_VECTOR_RAW_XAPI_TABLE in your configuration, update it to use ASPECTS_RAW_XAPI_TABLE instead.
For new installations or users switching to Vector, your data will be stored in the openedx database. You can migrate existing data from the xapi database to openedx if needed.
Installation
Aspects is implemented as a Tutor plugin. For now, the easiest installation method is via Tutor. Follow these steps for a tutor local installation:
Install Tutor: Follow the instructions at Tutor Installation Guide.
Create an Admin User: Refer to the Tutor Setup Guide.
Install and Enable the Plugin:
pip install tutor-contrib-aspects tutor plugins enable aspects tutor config saveTurn on In-Context Metrics (Optional): If using Open edX Teak or higher, in-context metrics can be enabled in Studio. See frontend-plugin-aspects for more information.
Rebuild Docker Images:
tutor images build openedx --no-cache tutor images build mfe --no-cache # Only necessary if using in-context metrics tutor images build aspects aspects-supersetInitialize the Environment:
tutor local do init
Data Population Options
To visualize data:
Generate test data:
tutor local do load-xapi-test-dataImport a demo course and create real data:
Follow these steps.
Interact with the course to generate data:
Complete a few activities within the course (e.g., enroll, take quizzes, watch videos) to generate real data. This will provide a more realistic dataset for analytics.
Personally Identifiable Information
Aspects does not collect learner PII by default. ASPECTS_ENABLE_PII turns collection on or off; run tutor config save and init to apply the change.
Enabling starts the user_profile and external_id sinks and unhides the charts that need learner names, usernames and emails. It only affects data from that point forward, so load the users that already exist with a one-time backfill:
tutor local do dump_data_to_clickhouse --options "--object user_profile"
tutor local do dump_data_to_clickhouse --options "--object external_id"Disabling stops those sinks, hides the charts again, and truncates the tables listed in EVENT_SINK_PII_MODELS on the next init, so PII collected while the setting was on does not remain in ClickHouse. The LMS stays the source of truth, so the backfill above repopulates them if it is turned back on.
xAPI S3 Sink Configuration
The S3 sink serves as a backup and safeguard for xAPI events. If ClickHouse is unavailable or encounters errors during event ingestion, events are stored in S3 as a safeguard. This ensures data durability and allows you to recover missed events later using the xapi-backfill command.
To enable this backup mechanism, configure the following settings:
ASPECTS_XAPI_S3_ACCESS_KEY=openedx
ASPECTS_XAPI_S3_BUCKET=xapi-events
ASPECTS_XAPI_S3_ENDPOINT=http://minio:9000
ASPECTS_XAPI_S3_REGION=us-east-1
ASPECTS_XAPI_S3_SECRET_KEY=...Vector S3 sink options:
ASPECTS_XAPI_S3_SINK_MAX_EVENTS=10000
ASPECTS_XAPI_S3_SINK_TIMEOUT_SECS=600xAPI S3 Backfill
If you have xAPI events stored in S3 (configured via ASPECTS_XAPI_S3_BUCKET), you can backfill them into ClickHouse using the xapi_block_storage_backfill command. This is useful for:
Restoring data from a backup
Importing data from another environment
Re-processing historical events
Basic usage:
tutor local do xapi_block_storage_backfillBy default, this imports all events. You can filter by date using year, month, day, and hour options:
tutor local do xapi_block_storage_backfill --year 2026 --month 3
tutor local do xapi_block_storage_backfill --year 2026 --month 03 --day 19
tutor local do xapi_block_storage_backfill --year 2026 --month 03 --day 19 --hour 14For flexible path matching, use the --path option to specify a custom S3 path:
tutor local do xapi_block_storage_backfill --path xapi/2026/03/19/14/*.log.zstAfter backfilling, you can run deduplication to remove duplicate events:
tutor local do xapi_block_storage_backfill --deduplicateOr run deduplication separately:
tutor local do xapi-deduplicateSync data from an existing Tutor installation with default settings:
tutor local do dump-data-to-clickhouse --options "--object course_overviews" tutor local do transform-tracking-logs --source_provider LOCAL --source_config '{"key": "/openedx/data", "container": "logs", "prefix": "tracking.log"}' --transformer_type xapi
Superset and Autoscaling
Superset Assets
Aspects maintains its Superset assets (dashboards, charts, datasets) in the repository. Local changes to these assets will be overwritten during updates unless saved as new assets.
To rebuild and re-import assets:
tutor images build aspects-superset --no-cache
tutor local do import-assetsAutoscaling
Aspects supports Kubernetes autoscaling configurations for Ralph, Superset, and Superset Worker via the Pod Autoscaling plugin. Modify autoscaling settings as needed.
Contributing Charts and Dashboards
To contribute Superset assets:
Fork this repository and set up a local Tutor instance with Aspects installed.
You should work on the non-localized versions of the Superset dashboards. Export the new or updated dashboard(s) using Superset’s “Export” feature. It is best to export the entire dashboard instead of just charts or datasets to ensure that all of the correct changes are captured.
Use the command:
tutor aspects import_superset_zip ~/Downloads/your_file.zipUpdate database connection strings to use template variables.
Validate and rebuild:
tutor images build aspects-superset --no-cache tutor aspects check_superset_assets tutor local do import-assetsSubmit a pull request with screenshots and details of your contributions.
Release Workflow
Releases are handled by repository maintainers via GitHub Actions:
Trigger the Bump version and changelog action to update the version and changelog.
Merge the PR to initiate the release and build-image workflows.
Ensure the updated version appears on PyPI and DockerHub.
Additional Resources
1 maintainer
Metadata
1 maintainer
Release files for tutor-contrib-aspects 6.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tutor_contrib_aspects-6.0.0.tar.gz | 172.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tutor_contrib_aspects-6.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 546.5 kB
Release files / tutor_contrib_aspects-6.0.0.tar.gz
| Download URL | tutor_contrib_aspects-6.0.0.tar.gz |
|---|---|
| Size | 172.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e4cfe2eef9e6a28251a1630ce1e8f4bee1547a0dede378344f728528c7fe0f5f
|
|
BLAKE2b-256 checksum How to use checksums |
dd9cbd4c59ded248a7b5f1d6118321ea0c275119e57dc32b44cb98f3a8735bc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / tutor_contrib_aspects-6.0.0-py3-none-any.whl
| Download URL | tutor_contrib_aspects-6.0.0-py3-none-any.whl |
|---|---|
| Size | 373.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
acb5a8a5e56a5f24b757d3d2c858a02f8b773afcacaec8f2438d1e5eaaece268
|
|
BLAKE2b-256 checksum How to use checksums |
c2cde9d8837b79ce6eae5b625f8f72a6695a6aff54eb0bd4902dd16e0e2ff2a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
