{"id":13665324,"url":"https://github.com/sbt/sbt-atmos","last_synced_at":"2025-04-21T12:30:46.253Z","repository":{"id":66188920,"uuid":"8572284","full_name":"sbt/sbt-atmos","owner":"sbt","description":"sbt plugin for running Typesafe Console in development","archived":false,"fork":false,"pushed_at":"2014-03-25T16:16:57.000Z","size":662,"stargazers_count":98,"open_issues_count":4,"forks_count":11,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-08-03T06:02:06.655Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-03-05T04:48:00.000Z","updated_at":"2022-06-27T19:52:16.000Z","dependencies_parsed_at":"2023-02-19T23:50:21.881Z","dependency_job_id":null,"html_url":"https://github.com/sbt/sbt-atmos","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-atmos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-atmos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-atmos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-atmos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbt","download_url":"https://codeload.github.com/sbt/sbt-atmos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223863905,"owners_count":17216234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-08-02T06:00:32.674Z","updated_at":"2024-11-09T18:11:59.427Z","avatar_url":"https://github.com/sbt.png","language":"Scala","funding_links":[],"categories":["OTHER"],"sub_categories":[],"readme":"sbt-atmos\n=========\n\n[sbt] plugin for running [Typesafe Console][console] in development.\n\nSupports tracing of [Akka projects](#akka-projects)\nand [Play projects](#play-projects).\n\n\n## Akka projects\n\n### Add plugin\n\nThis plugin requires sbt 0.12 or 0.13.\n\nAdd the sbt-atmos plugin to `project/plugins.sbt`. For example:\n\n```scala\naddSbtPlugin(\"com.typesafe.sbt\" % \"sbt-atmos\" % \"0.3.2\")\n```\n\nAdd the `atmosSettings` to the project. For a `.sbt` build, add a line with:\n\n```scala\natmosSettings\n```\n\nFor a full `.scala` build, add these settings to your project settings.\n\n```scala\ncom.typesafe.sbt.SbtAtmos.atmosSettings\n```\n\nFor example:\n\n```scala\nimport sbt._\nimport sbt.Keys._\nimport com.typesafe.sbt.SbtAtmos.{ Atmos, atmosSettings }\n\nobject SampleBuild extends Build {\n  lazy val sample = Project(\n    id = \"sample\",\n    base = file(\".\"),\n    settings = Defaults.defaultSettings ++ Seq(\n      name := \"Sample\",\n      scalaVersion := \"2.10.2\",\n      libraryDependencies += \"com.typesafe.akka\" %% \"akka-actor\" % \"2.2.0\"\n    )\n  )\n  .configs(Atmos)\n  .settings(atmosSettings: _*)\n}\n```\n\nA simple [sample Akka project][akka-sample] configured with the sbt-atmos plugin\nis included in this repository.\n\n\n### Trace dependencies\n\nThe sbt-atmos plugin will automatically add a library dependency which includes\nAspectj aspects for the Akka dependency being used, providing Akka is listed as\na library dependency of the project.\n\nTo explicitly specify the trace dependency, use the `traceAkka` helper method\nand pass the Akka version being used. For example, add a setting like this to\nyour build:\n\n```scala\ntraceAkka(\"2.2.1\")\n```\n\nThe full path to this method is:\n\n```scala\ncom.typesafe.sbt.SbtAtmos.traceAkka\n```\n\n\n### Run with Typesafe Console\n\nTo run your application with Typesafe Console there are extra versions of the\n`run` and `run-main` tasks. These use the same underlying settings for the\nregular `run` tasks, and also add the configuration needed to instrument your\napplication, and start and stop Typesafe Console.\n\nTo run the default or discovered main class use:\n\n    atmos:run\n\nTo run a specific main class:\n\n    atmos:run-main org.something.MainClass\n\n\n### Trace configuration\n\nIt's possible to configure which actors in your application are traced, and at\nwhat sampling rates.\n\nThe underlying configuration uses the [Typesafe Config][config] library. A\nconfiguration file is automatically created by the sbt-atmos plugin.\n\nThere are sbt settings to adjust the tracing and sampling of actors. Trace\nconfiguration is based on actor paths. For example:\n\n```scala\nimport com.typesafe.sbt.SbtAtmos.Atmos\nimport com.typesafe.sbt.SbtAtmos.AtmosKeys.{ traceable, sampling }\n\ntraceable in Atmos := Seq(\n  \"/user/someActor\" -\u003e true,  // trace this actor\n  \"/user/actors/*\"  -\u003e true,  // trace all actors in this subtree\n  \"*\"               -\u003e false  // other actors are not traced\n)\n\nsampling in Atmos := Seq(\n  \"/user/someActor\" -\u003e 1,     // sample every trace for this actor\n  \"/user/actors/*\"  -\u003e 100    // sample every 100th trace in this subtree\n)\n```\n\n**Note:** *The default settings are to collect all traces for all actors.\nFor applications with heavier loads you should select specific parts of the\napplication to trace.*\n\n\n### Configuration subsections\n\nActor systems are configured for tracing based on the same configuration\npassed on actor system creation. This allows applications with multiple actor\nsystems to have different trace configuration for each system, just like akka\nconfiguration. The sbt-atmos plugin will automatically add trace settings for\nthe top-level configuration. If your application creates actor systems using\nconfiguration subsections, like\n\n```scala\nval config = ConfigFactory.load()\nval system = ActorSystem(\"name\", config.getConfig(\"subsection\"))\n```\n\nthen these configuration subsections need to be marked for tracing too. This\ncan be done with the `includeConfig` setting. For example:\n\n```scala\nAtmosKeys.includeConfig in Atmos += \"subsection\"\n```\n\n\n## Play projects\n\n### Add plugin\n\nSupported Play versions are `2.1.4` (with sbt `0.12`),\nand `2.2.0` (with sbt `0.13`).\n\nAdd the sbt-atmos-play plugin to `project/plugins.sbt`. For example:\n\n```scala\naddSbtPlugin(\"com.typesafe.sbt\" % \"sbt-atmos-play\" % \"0.3.2\")\n```\n\nAdd the `atmosPlaySettings` to the project. For a `.sbt` build, add a line with:\n\n```scala\natmosPlaySettings\n```\n\nFor a full `.scala` build, add these settings to your project settings.\n\n```scala\ncom.typesafe.sbt.SbtAtmosPlay.atmosPlaySettings\n```\n\nFor example:\n\n```scala\nimport sbt._\nimport sbt.Keys._\nimport play.Project._\nimport com.typesafe.sbt.SbtAtmosPlay.atmosPlaySettings\n\nobject ApplicationBuild extends Build {\n  val appName    = \"traceplay\"\n  val appVersion = \"1.0\"\n\n  val main = play.Project(appName, appVersion).settings(atmosPlaySettings: _*)\n}\n```\n\nA simple [sample Play project][play-sample] configured with the sbt-atmos-play\nplugin is included in this repository.\n\n\n### Run with Typesafe Console\n\nTo run your Play application with Typesafe Console there is an alternative\nversion of the `run` task. This uses the same underlying settings for the\nregular `run` task, and also adds the configuration needed to instrument your\napplication, and start and stop Typesafe Console.\n\nFor Play 2.2, there is an alternative run task, which also traces the\napplication and starts Typesafe Console:\n\n```\natmos:run\n```\n\nFor Play 2.1, there is an alternative run command:\n\n```\natmos-run\n```\n\n\n## More information\n\nFor more information see the [documentation] for the developer version of\nTypesafe Console.\n\n\n## Feedback\n\nWe welcome your feedback and ideas for using Typesafe Console for development.\n\nYou can send feedback to the [Typesafe Console mailing list][email],\nor to [Typesafe Support][support],\n\n\n## License\n\n[Typesafe Console][console] is licensed under the [Typesafe Subscription Agreement][license]\nand is made available through the sbt-atmos plugin for development use only.\n\nThe code for the sbt-atmos plugin is open source software licensed under the\n[Apache 2.0 License][apache].\n\nFor more information see [Typesafe licenses][licenses].\n\n\n## Contribution policy\n\nContributions via GitHub pull requests are gladly accepted from their original\nauthor. Before we can accept pull requests, you will need to agree to the\n[Typesafe Contributor License Agreement][cla] online, using your GitHub account.\n\n\n[sbt]: https://github.com/sbt/sbt\n[console]: http://typesafe.com/platform/runtime/console\n[akka-sample]: https://github.com/typesafehub/sbt-atmos/tree/v0.3.2/sample/abc\n[play-sample]: https://github.com/typesafehub/sbt-atmos/tree/v0.3.2/sample/play\n[forked]: http://www.scala-sbt.org/0.12.4/docs/Detailed-Topics/Forking.html\n[config]: https://github.com/typesafehub/config\n[documentation]: http://resources.typesafe.com/docs/console\n[support]: http://support.typesafe.com\n[email]: http://groups.google.com/group/typesafe-console\n[license]: http://typesafe.com/assets/legal/TypesafeSubscriptionAgreement.pdf\n[apache]: http://www.apache.org/licenses/LICENSE-2.0.html\n[licenses]: http://typesafe.com/legal/licenses\n[cla]: http://www.typesafe.com/contribute/cla\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-atmos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbt%2Fsbt-atmos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-atmos/lists"}