{"id":13935595,"url":"https://github.com/google-deepmind/envlogger","last_synced_at":"2026-03-05T09:01:32.786Z","repository":{"id":37537192,"uuid":"390403319","full_name":"google-deepmind/envlogger","owner":"google-deepmind","description":"A tool for recording RL trajectories.","archived":false,"fork":false,"pushed_at":"2025-07-29T18:57:58.000Z","size":485,"stargazers_count":109,"open_issues_count":2,"forks_count":15,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-11-20T12:03:12.241Z","etag":null,"topics":["logging","reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-deepmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-28T15:35:08.000Z","updated_at":"2025-11-12T16:24:13.000Z","dependencies_parsed_at":"2023-09-07T20:34:48.190Z","dependency_job_id":"cecc75d5-3d3e-411a-b262-44fc121615a2","html_url":"https://github.com/google-deepmind/envlogger","commit_stats":null,"previous_names":["google-deepmind/envlogger","deepmind/envlogger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/google-deepmind/envlogger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fenvlogger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fenvlogger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fenvlogger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fenvlogger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-deepmind","download_url":"https://codeload.github.com/google-deepmind/envlogger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fenvlogger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30117476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T08:19:04.902Z","status":"ssl_error","status_checked_at":"2026-03-05T08:17:37.148Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["logging","reinforcement-learning"],"created_at":"2024-08-07T23:01:54.933Z","updated_at":"2026-03-05T09:01:32.287Z","avatar_url":"https://github.com/google-deepmind.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# EnvironmentLogger\n\n`EnvLogger` is a standard `dm_env.Environment` class wrapper that\nrecords interactions between a real environment and an agent. These interactions\nare saved on disk as trajectories and can be retrieved in whole, by individual\ntimesteps or by specific episodes.\n\n![drawing](docs/images/envlogger.png \"EnvironmentLogger Diagram\")\n\n## Metadata\n\nTo better categorize your logged data, you may want to add some tags in the\nmetadata when you construct the logger wrapper. The metadata is written once per\n`EnvLogger` instance.\n\n```python\nenv = envlogger.EnvLogger(\n    env,\n    data_directory='/tmp/experiment_logs',\n    metadata={\n        'environment_type': 'dm_control',\n        'agent_type': 'D4PG'\n    })\n```\n## How to use Envlogger\n\nNOTE: Ensure that `data_directory` exists _before_ instantiating the wrapper.\n\nMost of the time, it is just a one-liner wrapper, e.g.\n\n```python\nimport envlogger\nfrom envlogger.testing import catch_env\nimport numpy as np\n\nenv = catch_env.Catch()\nwith envlogger.EnvLogger(\n    env, data_directory='/tmp/experiment_logs') as env:\n\n  env.reset()\n  for step in range(100):\n    action = np.random.randint(low=0, high=3)\n    timestep = env.step(action)\n```\n\nFull example of random agent in Catch is available here:\n[random_agent_catch.py](https://github.com/google-deepmind/envlogger/tree/main/envlogger/examples/random_agent_catch.py)\n\n\n### Step metadata\n\nEnvlogger also allows to record custom metadata per step by defining a function\nthat can be passed to the wrapper. In this example, we want to record the\ntimestamp of when each step was produced:\n\n```python\n\n  def step_fn(unused_timestep, unused_action, unused_env):\n    return {'timestamp': time.time()}\n\n  ...\n\n  with envlogger.Envlogger(\n    env,\n    data_directory='/tmp/experiment_logs',\n    step_fn=step_fn) as env:\n\n  ...\n\n```\n\n### Episode metadata\n\nRecording custom episode metadata is also possible by providing a callback. This\ncallback is invoked at every step but only the last value returned that is not\n`None` (if any) is stored.\n\nIn the following example, we only store the timestamp of the first step of the\nepisode.\n\n```python\n\n  def episode_fn(timestep, unused_action, unused_env):\n    if timestemp.first:\n      return {'timestamp': time.time()}\n    else:\n      return None\n\n  ...\n\n  with envlogger.Envlogger(\n    env,\n    data_directory=FLAGS.trajectories_dir,\n    episode_fn=episode_fn) as env:\n\n  ...\n\n```\n\n### TFDS backend\n\nEnvlogger supports writing data that is directly compatible with\n[TFDS](http://www.tensorflow.org/datasets) and [RLDS].\n\nFor that, you need to indicate the specs of your environment in terms of [TFDS\nFeatures](https://www.tensorflow.org/datasets/features) using an RLDS [DatasetConfig] like in the example\n(note that the config can include `step_metadata_info`and `episode metadata_info`).\n\n```\n  dataset_config = tfds.rlds.rlds_base.DatasetConfig(\n      name='catch_example',\n      observation_info=tfds.features.Tensor(\n          shape=(10, 5), dtype=tf.float32,\n          encoding=tfds.features.Encoding.ZLIB),\n      action_info=tf.int64,\n      reward_info=tf.float64,\n      discount_info=tf.float64)\n```\n\nAnd then use the [TFDS Backend] when instantiating the Envlogger:\n\n```\nenvlogger.EnvLogger(\n      env,\n      backend = tfds_backend_writer.TFDSBackendWriter(\n        data_directory=FLAGS.trajectories_dir,\n        split_name='train',\n        max_episodes_per_file=500,\n        ds_config=dataset_config),\n  )\n```\n\nA full example is available here [random_agent_catch.py](https://github.com/google-deepmind/envlogger/tree/main/envlogger/examples/tfds_random_agent_catch.py)\n\n\n[RLDS]: http://github.com/google-research/rlds\n[DatasetConfig]: https://github.com/tensorflow/datasets/blob/fdad1d9e8f1cb34389a336132b2f842cbc7aca57/tensorflow_datasets/rlds/rlds_base.py#L29\n[TFDS Backend]:https://github.com/deepmind/envlogger/blob/main/envlogger/backends/tfds_backend_writer.py\n\nNote: If you are installing Envlogger via pip, remember to install the extra\ndependencies:\n\n```\npip install envlogger[tfds]\n```\n\n[RLDS Creator]: http://github.com/google-research/rlds-creator\n\n## Reading stored trajectories\n\n`Reader` can read stored trajectories. Example:\n\n```python\nfrom envlogger import reader\n\nwith reader.Reader(\n    data_directory='/tmp/experiment_logs') as r:\n  for episode in r.episodes:\n    for step in episode:\n       # step is a step_data.StepData.\n       # Use step.timestep.observation, step.timestep.reward, step.action etc...\n```\n\n### Reading the dataset with TFDS/RLDS\n\nDatasets generated with Envlogger are compatible with [RLDS].\n\nIf you used the [TFDS backend](#tfds_backend), you can read your data directly\nwith `tfds.builder_from_directory`. Check the [RLDS] website for colabs and\ntools to manipulate your datasets.\n\nOtherwise, you can transform them into a [TFDS](http://www.tensorflow.org/datasets)\ncompatible dataset (learn how in the [RLDS] documentation).\n\n[RLDS]: http://github.com/google-research/rlds\n\n## Getting Started\n\n\u003e EnvLogger currently only supports Linux based OSes and Python 3.\n\nYou can install EnvLogger via `pip`:\n\n```\npip install envlogger\n```\n\nIf you want to use the TFDS backend, you need to install the package with\nextra dependencies:\n\n```\npip install envlogger[tfds]\n```\n\n##### Compiling from source\n\nFor this option you will need to [install Bazel](https://docs.bazel.build/versions/main/install.html) and [GMP](https://gmplib.org/) (`libgmp-dev` on Debian-based systems).\nPlease note that Bazel versions \u003e4.0 are not supported. Our recommended version\nis [3.7.2](https://github.com/bazelbuild/bazel/releases/tag/3.7.2). Then:\n\n```\ngit clone https://github.com/deepmind/envlogger/\ncd envlogger\nbazel test --test_output=errors envlogger/...\n```\n\n##### Running inside Docker\n\nWe provide a Docker image that can be used to run tests in a more controlled\nenvironment. You can run it as follows:\n\n```\nsh docker/build.sh\ndocker run -it envlogger bash\nbazel test --test_output=errors envlogger/...\n```\n\n## Benchmarks\n\nWrapping your environment with EnvLogger adds an approximately 2 millisecond overhead per environment step.\nSee the following difference in distributions in the case of random agent on a 100 steps per second Catch environment (measured in milliseconds).\n\nPercentiles      | 50th      | 95th       | 99th      | 99.9th     | mean (± std)\n---------------- | --------- | -----------| ----------| -----------| -----------\nw/o EnvLogger    | 10.15     | 10.23      | 11.51     | 14.70      | 10.19 (± 1.06)\nw/ EnvLogger     | 12.65     | 14.39      | 15.94     | 19.43      | 12.88 (± 0.34)\n\n\u003cimg src=\"docs/images/timings.png\" width=\"40%\"\u003e\n\n\n## Acknowledgements\n\nWe greatly appreciate all the support from the\n[TF-Agents](https://github.com/tensorflow/agents) team in setting up building\nand testing for EnvLogger.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fenvlogger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-deepmind%2Fenvlogger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fenvlogger/lists"}