mention cal_logs in docs

changes/9257.docs.rst

@@ -0,0 +1 @@
+Add cal_logs documentation.

docs/index.rst

@@ -55,7 +55,7 @@ is also available on `JDox <https://jwst-docs.stsci.edu>`__.
    jwst/user_documentation/running_pipeline_command_line.rst
    jwst/user_documentation/available_pipelines.rst
    jwst/user_documentation/input_output_file_conventions.rst
-   jwst/user_documentation/logging_configuration.rst
+   jwst/user_documentation/logging.rst
    jwst/user_documentation/datamodels.rst
    jwst/user_documentation/pub_deprecation.rst
    jwst/user_documentation/more_information.rst

docs/jwst/user_documentation/logging_configuration.rst → docs/jwst/user_documentation/logging.rst

@@ -1,6 +1,39 @@
-=====================
-Logging Configuration
-=====================
+.. _logging:
+
+=======
+Logging
+=======
+
+.. _cal_logs:
+
+DataModel cal_logs
+==================
+
+Saved files that contain :ref:`jwst-data-models` will contain log messages
+from the run that produced the file. These are stored in the ASDF portion
+of the file and can be inspected by opening the file as a
+:ref:`jwst-data-models`.
+
+The ``cal_logs`` attribute contains log messages as lists of strings
+organized by step or pipeline name. For example to see log messages from
+:ref:`calwebb_detector1`:
+
+::
+
+        import stdatamodels.jwst.datamodels as dm
+        model = dm.open("jw00001001001_01101_00001_mirimage_cal.fits")
+        print(model.cal_logs.calwebb_detector1)
+
+Files processed by a pipeline will contain all logs messages for that
+run under the pipeline name (and not contain ``cal_logs`` for individual
+steps that were part of the pipeline).
+
+Log messages that contain sensitive information (user, hostname, paths,
+IP addresses) are replaced with empty strings. Please see the console
+logs for those messages.
+
+Configuration
+=============
 
 The name of a file in which to save log information, as well as the desired
 level of logging messages, can be specified in an optional configuration file.