docs: Add troubleshooting doc

docs/technical_documentation/how-tos/backfill.rst

@@ -1,12 +1,12 @@
 Backfill old or missing data
-*****************************
+****************************
 
 If you are bootstrapping a new Open edX platform with Aspects or experiencing service
 downtime in Ralph or Vector, you may need to backfill the old data. This guide will
 provide you with step-by-step instructions on how to perform the backfill process.
 
 Backfill xAPI data from tracking logs
-######################################
+#####################################
 
 Event routing backends provide a management command to backfill old or missing
 data. The command is called ``transform_tracking_logs``, learn more about it in the
@@ -57,7 +57,7 @@ Which will run the LMS management command:
 
 .. code-block:: console
 
-    ./manage.py lms transform_tracking_logs --transformer_type xapi --source_provider S3 --source_config '{"key": "aws-key", "secret": "aws-secret", "region": "bucket-region", "container": "bucket-name", "prefix":"any-prefix"}' --destination_provider LRS --transformer_type xapi
+    ./manage.py lms transform-tracking-logs --transformer_type xapi --source_provider S3 --source_config '{"key": "aws-key", "secret": "aws-secret", "region": "bucket-region", "container": "bucket-name", "prefix":"any-prefix"}' --destination_provider LRS --transformer_type xapi
 
 
 This will create a k8s job that will send all the tracking logs from S3 bucket to the configured
@@ -79,21 +79,39 @@ the ClickHouse S3 table function.
 .. _backfill_course_blocks:
 
 Backfill course blocks
-#######################
+######################
 
 Aspects keeps a synchronized copy of some course metadata in Clickhouse. This copy is used to
 generate reports and to provide a fast way to query the courses. The copy is updated
 every time a course is published. However, if a course is published before Aspects
 is installed, the course will not be copied to Clickhouse.
 
-Aspects provides a wrapper around the command ``dump_data_to_clickhouse`` that
-will backfill any missing courses. To learn more about the command, read the
-`Event Sink Clickhouse documentation <https://github.com/openedx/openedx-event-sink-clickhouse#commands>`_.
+Aspects provides a wrapper around the command ``dump-data-to-clickhouse`` that
+will backfill any missing courses. To learn more about the command including some important,
+options, read the
+`Platform Plugin Aspects documentation <https://github.com/openedx/platform-plugin-aspects?tab=readme-ov-file#commands>`_.
 
 To backfill the courses, run:
 
 .. code-block:: console
 
     # If you already have some courses in your clickhouse sink, its better to
-    # drop --options "--force" as it will create duplicates of the pre-existing courses.
-    tutor [dev|local|k8s] do dump_data_to_clickhouse --service cms --object course_overviews --options "--force"
+    # drop "--force" as it will create duplicates of the pre-existing courses.
+    tutor [dev|local|k8s] do dump-data-to-clickhouse --service cms --options "--object course_overviews --force"
+
+
+.. _backfill_pii:
+
+Backfill User PII
+#################
+
+If you have user PII turned on this data can also be backfilled using the
+``dump-data-to-clickhouse`` command as above.
+
+To backfill the user profile and external ids needed to identify users variations on this command
+can be run (again please see the documentation for details and other important options):
+
+.. code-block:: console
+
+    tutor [dev|local|k8s] do dump-data-to-clickhouse --service lms --options "--object user_profile"
+    tutor [dev|local|k8s] do dump-data-to-clickhouse --service lms --options "--object external_id"

docs/technical_documentation/how-tos/index.rst

@@ -8,16 +8,17 @@ How-Tos
    Aspects Plugin for Tutor <install_aspects>
    Upgrade Aspects <upgrade>
    Configure Aspects for Production <production_configuration>
-   Changing the xAPI actor identifier <changing_actor_identifier>
    Backfill old or missing data <backfill>
+   Troubleshooting Aspects <troubleshooting_aspects>
+   Connect to external Clickhouse database <remote_clickhouse>
+   Changing the xAPI actor identifier <changing_actor_identifier>
    Superset extra assets <superset_extra_assets>
    Superset language settings <superset_language_settings>
    Superset extra row level security <superset_row_level_security>
    Superset extra jinja filters <superset_jinja_filters>
    Superset custom roles <superset_roles>
    Superset custom config settings <superset_config_docker>
    Clickhouse extra SQL <clickhouse_sql>
-   Connect to external Clickhouse database <remote_clickhouse>
    Extending dbt <dbt_extensions>
    Run Aspects in a ClickHouse cluster <clickhouse_cluster>
    xAPI Transforms <xapi_transforms>

docs/technical_documentation/how-tos/troubleshooting_aspects.rst

@@ -0,0 +1,76 @@
+.. _troubleshooting_aspects:
+
+Troubleshooting Aspects
+#######################
+
+Most common problems with Aspects can be fixed by making sure everything is up to date by deleting
+any potentially orphaned Superset assets, rebuilding Docker images, and re-initializing Aspects:
+
+- From your TUTOR_ROOT: ``rm -rf env/plugins/aspects``
+- ``tutor config save``
+- ``tutor images build openedx aspects aspects-superset``
+- ``tutor [dev|local|k8s] do init -l aspects``
+
+  - This may take a long time if you have lots of data!
+
+
+Common Issues
+*************
+In some cases things can get into a state which isn't resolved by those steps, below are some
+common Aspects problems and how to fix them.
+
+
+Superset Logo Just Spins
+========================
+
+Symptom: In the Instructor Dashboard "Reports" tab, In-Context Metrics in Studio, or in Superset,
+some or all Superset dashboards appear to load but the "S" logo just spins and no data appears.
+
+Causes: This most often happens where ClickHouse has no data for filters needed to display a
+dashboard.
+
+Solution: Make sure you have published your courses since installing / reinstalling Aspects, or :ref:`backfill course blocks <backfill_course_blocks>` .
+
+
+Embedded Dashboard Errors
+=========================
+
+Symptom: In the Instructor Dashboard "Reports" tab or In-Context Metrics in Studio the dashboards
+fail to load, showing only a message like:
+
+- ``Something went wrong with embedded authentication. Check the dev console for details.``
+- or ``Error: invalid_request Invalid client_id``
+
+This most often happens when moving between Tutor deployment types (dev/local/k8s) but can also
+happen when the hostnames or ports your LMS or Superset change (such as when populating a staging
+environment from a production database). This is usually an issue with the OAuth Application entry
+not matching the Superset URL. Make sure you ``config.yml`` settings are correct for your
+environment (especially ``SUPERSET_HOST`` and ``SUPERSET_PORT``) then:
+
+- Go into the Django admin: ``{LMS_ROOT}/admin/oauth2_provider/application/``
+- Delete the Application entries for `superset-sso` and ``superset-sso-dev`` if they exist
+- Re-run ``tutor [dev|local|k8s] do init -l aspects`` to recreate the entries
+
+
+General Troubleshooting
+***********************
+
+Logs to check for errors:
+
+When running with the Ralph data pipeline:
+
+- lms-worker
+- cms-worker
+- ralph
+
+When running with the Vector data pipeline:
+
+- lms
+- cms
+- vector
+
+When running with the event bus data pipeline:
+
+- lms
+- cms
+- aspects-consumer