Package: tutor-cairn
Analytics are an essential component of an online learning platform: you need to know whether your courses are effective and which parts need some improvement. You need to know if your students are falling by, and if they do, you need to detect the early warning signs. When your courses are successful, you want to get periodical engagement reports.We created a tool to help you answer all these questions. Cairn is a Tutor plugin that you install on top of an Open edX platform and that gives you access to a powerful, full-blown analytics stack. Cairn comes with the following features out of the box:❄️Unified data lake of learner events and stateful data: both learner-triggered events, coming from the Open edX tracking logs, and stateful data, coming from the existing databases, are available for querying in a single unified interface. This means that you can, for instance, query the grades of the students that visited your platform in the past 24 hours, or collect the email addresses of the students who did not yet complete the latest assignment.⚡﻿Real-time:new events are visible immediately in your analytics interface. No more waiting for slow batch jobs to complete!🔑Course- and org-based data access rights:your course staff is granted access only to the data rows that concern them. Cairn makes it easy to create new users with granular access permissions.🎁Working dashboards out of the box:Cairn comes with a fully functional dashboard that you can start playing with right away.🛠️Fully customizable data and dashboards:your data scientists, business intelligence team and other tinkerers can freely explore your course data, create and share their own queries, datasets and dashboards. All it takes is a little bit of SQL.🚀Scalable:Cairn scales as much as its backend, which was designed for Internet scale.Cairn vs alternativesList of featuresCairnOpen edX InsightsFiguresEvent aggregation✅✅❌Real-time data✅❌✅Easy to install✅❌✅Custom queries and dashboards✅❌❌Works with the latest Open edX versions✅✅❌How does Cairn work?Cairn uses the same collect/store/expose paradigm made popular by other frameworks such as theELK Stack– excepts that all the components are different and better suited to Open edX:On the server side, tracking logs are collected byVector, an efficient, cloud-native log collector.Tracking log events are then stored in aClickhousetable, which is the cornerstone of Cairn. Clickhouse also exposes MySQL data via live and materialized views. This is the magic piece of the puzzle which allows us to join event and MySQL data.The data inside Clickhouse is made visible to the end-users in aSupersetfrontend.InstallationCairn used to be a commercial plugin, but is now available for free to all Tutor users. Install the plugin with:tutor plugins install cairnUsageGetting startedEnable the plugin with:tutor plugins enable cairnThen, restart your platform and run the initialization scripts:tutor local launchOpen http(s)://data.<YOUR_LMS_HOST> in your browser. When running locally, this will behttp://data.local.edly.io. (http://data.local.edly.io:2247in development). Users authenticate with their LMS user. By default, they have access to the data generated by the courses in which they have the “staff role”. Once a user has successfully logged-in, their account can be modified with thecairn-createusercommand.For instance, to convert an existing user to administrator status, run:tutor local do cairn-createuser --admin YOURUSERNAME YOURUSERNAME@YOUREMAIL.COMTo add the default dashboards to the new user, add the--bootstrap-dashboardsoption:tutor local do cairn-createuser --bootstrap-dashboards YOURUSERNAME YOURUSERNAME@YOUREMAIL.COMSome event data might be missing from your dashboards: just start using your LMS and refresh your dashboard. The new events should appear immediately.By default,AUTH_ROLES_SYNC_AT_LOGINisfalsewhich means admin can customize the permissions associated to a user. To disable this behaviour, modify theCAIRN_AUTH_ROLES_SYNC_AT_LOGINsetting:tutor config save --set CAIRN_AUTH_ROLES_SYNC_AT_LOGIN=true
tutor local restart⚠️ WARNING ⚠️ Previous versions (v15 and earlier) of Cairn required manual user management. If you have an existing installation of Cairn, this behaviour will change when you upgrade to v16. To revert to the previous behaviour, see“manual user management”below.Available metricsCairn allows you to collect and view just any metric from your Open edX platform, as long as the data is available from the tracking logs or the MySQL database. Out of the box, the default Cairn dashboard comes with visualizations for the following metrics:Weekly course engagement:Number of enrolled learnersNumber of active learnersNumber of learners who watched a videoNumber of learners who tried a problemAverage time spent in courseCourse progress:Number of students who completed each unitGrade distribution histogramCourse demographics:Gender distributionLevel of education distributionVideo engagement:Number of unique viewersAverage watch timeTotal watch timeSecond-per-second statistics: Number of unique viewers, Total number of viewsManual user managementBy default, authentication uses single sign-on (SSO) with the LMS such that users do not have to create separate accounts in Superset. In previous versions of Cairn (v15 and earlier), user accounts had to be created manually. To restore this behaviour, modify theCAIRN_ENABLE_SSOsetting:tutor config save --set CAIRN_ENABLE_SSO=false
tutor local restartSSO will then disabled, and only manually created users will be able to login. To create a user, run thecairn-createusercommand, as explained above:tutor local do cairn-createuser --password=yourpassword YOURUSERNAME YOURUSERNAME@YOUREMAIL.COMTo restrict a given user to one or more courses or organizations, select the course IDs and/or organization IDS to which the user should have access:tutor local do cairn-createuser --course-id='course-v1:edX+DemoX+Demo_Course' YOURUSERNAME YOURUSERNAME@YOUREMAIL.COMRefreshing course block dataCourse block IDs and names are loaded from the Open edX modulestore into the datalake. After making changes to your course, you might want to refresh the course structure stored in the datalake. To do so, run:tutor local do init --limit=cairnOr, if you want to avoid running the full plugin initialization:tutor local run \
    -v $(tutor config printroot)/env/plugins/cairn/apps/openedx/scripts/:/openedx/scripts \
    -v $(tutor config printroot)/env/plugins/cairn/apps/clickhouse/auth.json:/openedx/clickhouse-auth.json \
    lms python /openedx/scripts/importcoursedata.pyRunning on KubernetesWhen running on Kubernetes instead of locally, most commands above can be re-written withtutor k8s exec service "command"instead oftutor local run service command. For instance:# Privileged user creation
tutor k8s exec cairn-superset "superset fab create-admin --username YOURUSERNAME --email user@example.com"
# Unprivileged user creation
tutor k8s exec cairn-clickhouse "cairn createuser --course-id='course-v1:edX+DemoX+Demo_Course' --org-id='edX' YOURUSERNAME"
tutor k8s exec cairn-superset "cairn createuser YOURUSERNAME YOURUSERNAME@YOUREMAIL.COM"Collecting past eventsWhen Cairn is launched for the first time, past events that were triggered prior to the plugin installation will not be loaded in the data lake. If you are interested in loading past events, you should load them manually by running:tutor local start -d cairn-clickhouse
tutor local run \
  --volume="$(tutor config printroot)/data/lms/logs/:/var/log/openedx/:ro" \
  --volume="$(tutor config printroot)/env/plugins/cairn/apps/vector/file.toml:/etc/vector/file.toml:ro" \
  -e VECTOR_CONFIG=/etc/vector/file.toml cairn-vectorThe latter command will parse tracking log events from the$(tutor configprintroot)/data/lms/logs/tracking.logfile that contains all the tracking logs since the creation of your platform. The command will take a while to run if you have a large platform that has been running for a long time. It can be interrupted at any time and started again, as the log collector keeps track of its position within the tracking log file.Adding data to your data lakeTables created in Clickhouse are managed by a lightweight migration system. You can view existing migrations that ship by default with Cairn in the following folder:$VIRTUAL_ENV/lib/python3.8/site-packages/tutorcairn/templates/cairn/apps/clickhouse/migrations.d/.You are free to create your own migrations that will automatically be created in Clickhouse every time thetutor local launchortutor local do initcommands are run. To do so, as usual in Tutor, you should create aTutor plugin. This plugin should include theCAIRN_MIGRATIONS_FOLDERconfiguration. This setting should point to a template folder, inside the plugin, where migration templates are defined. For instance, assuming you created the “customcairn” plugin:config = {
    "defaults": {
        "CAIRN_MIGRATIONS_FOLDER": "customcairn/apps/migrations.d"
    }
}In this example, the following folder should be created in the plugin::tutorcustomcairn/templates/customcairn/apps/migrations.d/. Then, you should add your migration files there. Migrations will be applied in alphabetical order whenever you runtutor local launchortutor local do init.DevelopmentIn development, the Superset user interface will be available athttp://data.local.edly.io:2247.To reload Vector configuration after changes to vector.toml, run:tutor config save && tutor local exec cairn-vector sh -c "kill -s HUP 1"To explore the clickhouse database as root, run:tutor local run cairn-clickhouse cairn clientTo launch a Python shell in Superset, run:tutor local run cairn-superset superset shellConfigurationCairn is configured by several Tutor settings. Each one of these settings may be modified individually by running:tutor config save --set SETTING_NAME=settingvalueThen apply changes with:tutor local launchGeneral settingsCAIRN_HOST(default:"data.{{LMS_HOST }}"): hostname at which the Cairn frontend (i.e: Superset) will be accessible. By default, this is the “data” subdomain of the LMS. Thus, if your students access the LMS athttps://learn.mydomain.comthen Cairn will be accessible athttps://data.learn.mydomain.com.CAIRN_DOCKER_HOST_SOCK_PATH(default:"/var/run/docker.sock"): path to the Docker host socket on the host. This is required to collect logs from Docker when running locally, but it is not used when running on Kubernetes.Clickhouse settingsCAIRN_RUN_CLICKHOUSE(default:true): set tofalseto run your own Clickhouse cluster separately from Cairn. In that case, you should also configure the Clickhouse credentials below.CAIRN_CLICKHOUSE_DOCKER_IMAGE(default:"{{ DOCKER_REGISTRY}}overhangio/cairn-clickhouse:{{CAIRN_VERSION }}"): name of the Docker image that runs Clickhouse. Override this setting to build your own image of Clickhouse.CAIRN_CLICKHOUSE_HOST(default:"cairn-clickhouse"): hostname where Clickhouse will be accessible from Superset. By default, this is the internal docker-compose/Kubernetes service name.CAIRN_CLICKHOUSE_HTTP_PORT(default:8123): port at which Clickhouse exposes its HTTP API, which is necessary to bulk import unit names.CAIRN_CLICKHOUSE_HTTP_SCHEME(default:"http"): HTTP scheme to access the Clickhouse HTTP API. If you self-host a Clickhouse cluster (RUN_CLICKHOUSE=false) then it is strongly recommended to set this to “https”.CAIRN_CLICKHOUSE_PORT(default:9000): native Clickhouse API port.CAIRN_CLICKHOUSE_DATABASE(default:"openedx"): name of the Clickhouse database which will store all analytics from your Open edX platform.CAIRN_CLICKHOUSE_USERNAME(default:"openedx"): username to access theCAIRN_CLICKHOUSE_DATABASE.CAIRN_CLICKHOUSE_PASSWORD(default:"{{ 20|random_string }}"): randomly-generated password forCAIRN_CLICKHOUSE_USERNAME.Postgresql/Superset settingsCAIRN_RUN_POSTGRESQL(default:true): set tofalseto run your own Postgresql cluster separately from Cairn. Postgresql is the database that stores all data related to Superset, which is the Cairn frontend.CAIRN_SUPERSET_LANGUAGE_CODE(default:"{{LANGUAGE_CODE[:2]}}"): 2-letter code of the default language for the Superset frontend. View the list of all supported languageshere. When different than “en”, users will have the opportunity to switch from English to this language via a flag icon in the top-right corner.CAIRN_SUPERSET_DOCKER_IMAGE(default:"{{ DOCKER_REGISTRY}}overhangio/cairn-superset:{{CAIRN_VERSION }}"): name of the Docker image that runs Postgresql.CAIRN_POSTGRESQL_DATABASE(default:"superset"): name of the Postgresql database.CAIRN_POSTGRESQL_USERNAME(default:"superset"): Postgresql username.CAIRN_POSTGRESQL_PASSWORD(default:"{{ 20|random_string }}"): Postgresql password.CAIRN_SUPERSET_SECRET_KEY(default:"{{ 20|random_string }}"): randomly-generated secret key for the Superset frontend.TroubleshootingThis Tutor plugin is maintained by Fahad Khalid fromEdly. Community support is available from the officialOpen edX forum. Do you need help with this plugin? See thetroubleshootingsection from the Tutor documentation.LicenseThis software is licensed under the terms of the AGPLv3.