From 04fd82e14057c5c2d28682ce8855fbe752d2782d Mon Sep 17 00:00:00 2001 From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Date: Sun, 5 Sep 2021 16:00:02 -0400 Subject: [PATCH] [APM] Clean up readme (#110973) (#111237) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [APM] Clean up readme * Update linting.md * Update testing.md * Update testing.md * Update testing.md * Update plugin-list.asciidoc Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Søren Louv-Jansen --- docs/developer/plugin-list.asciidoc | 2 +- x-pack/plugins/apm/dev_docs/feature_flags.md | 14 +++ x-pack/plugins/apm/dev_docs/linting.md | 22 +++++ x-pack/plugins/apm/dev_docs/local_setup.md | 50 +++++++++++ x-pack/plugins/apm/dev_docs/testing.md | 66 ++++++++++++++ x-pack/plugins/apm/readme.md | 93 ++------------------ x-pack/plugins/apm/scripts/test/README.md | 64 +------------- 7 files changed, 162 insertions(+), 149 deletions(-) create mode 100644 x-pack/plugins/apm/dev_docs/feature_flags.md create mode 100644 x-pack/plugins/apm/dev_docs/linting.md create mode 100644 x-pack/plugins/apm/dev_docs/local_setup.md create mode 100644 x-pack/plugins/apm/dev_docs/testing.md diff --git a/docs/developer/plugin-list.asciidoc b/docs/developer/plugin-list.asciidoc index 5aa70d71183c..4332f0ce051c 100644 --- a/docs/developer/plugin-list.asciidoc +++ b/docs/developer/plugin-list.asciidoc @@ -354,7 +354,7 @@ The plugin exposes the static DefaultEditorController class to consume. |{kib-repo}blob/{branch}/x-pack/plugins/apm/readme.md[apm] -|To access an elasticsearch instance that has live data you have two options: +|Local setup documentation |{kib-repo}blob/{branch}/x-pack/plugins/banners/README.md[banners] diff --git a/x-pack/plugins/apm/dev_docs/feature_flags.md b/x-pack/plugins/apm/dev_docs/feature_flags.md new file mode 100644 index 000000000000..9f722dd5eac5 --- /dev/null +++ b/x-pack/plugins/apm/dev_docs/feature_flags.md @@ -0,0 +1,14 @@ +## Feature flags + +To set up a flagged feature, add the name of the feature key (`apm:myFeature`) to [commmon/ui_settings_keys.ts](./common/ui_settings_keys.ts) and the feature parameters to [server/ui_settings.ts](./server/ui_settings.ts). + +Test for the feature like: + +```js +import { myFeatureEnabled } from '../ui_settings_keys'; +if (core.uiSettings.get(myFeatureEnabled)) { + doStuff(); +} +``` + +Settings can be managed in Kibana under Stack Management > Advanced Settings > Observability. \ No newline at end of file diff --git a/x-pack/plugins/apm/dev_docs/linting.md b/x-pack/plugins/apm/dev_docs/linting.md new file mode 100644 index 000000000000..a4fd3094f121 --- /dev/null +++ b/x-pack/plugins/apm/dev_docs/linting.md @@ -0,0 +1,22 @@ +## Linting + +_Note: Run the following commands from the root of Kibana._ + +### Typescript + +``` +node scripts/type_check.js --project x-pack/plugins/apm/tsconfig.json +``` + +### Prettier + +``` +yarn prettier "./x-pack/plugins/apm/**/*.{tsx,ts,js}" --write +``` + +### ESLint + +``` +node scripts/eslint.js x-pack/legacy/plugins/apm +``` +diff --git a/x-pack/plugins/apm/dev_docs/feature_flags.md b/x-pack/plugins/apm/dev_docs/feature_flags.md diff --git a/x-pack/plugins/apm/dev_docs/local_setup.md b/x-pack/plugins/apm/dev_docs/local_setup.md new file mode 100644 index 000000000000..d977f4444514 --- /dev/null +++ b/x-pack/plugins/apm/dev_docs/local_setup.md @@ -0,0 +1,50 @@ +## Local environment setup + +### Kibana + +``` +git clone git@github.com:elastic/kibana.git +cd kibana/ +yarn kbn bootstrap +yarn start --no-base-path +``` + +### APM Server, Elasticsearch and data + +To access an elasticsearch instance that has live data you have two options: + +#### A. Connect to Elasticsearch on Cloud (internal devs only) + +Find the credentials for the cluster [here](https://github.com/elastic/apm-dev/blob/master/docs/credentials/apm-ui-clusters.md#apmelstcco) + +#### B. Start Elastic Stack and APM data generators + +``` +git clone git@github.com:elastic/apm-integration-testing.git +cd apm-integration-testing/ +./scripts/compose.py start master --all --no-kibana +``` + +_Docker Compose is required_ + +### Setup default APM users + +APM behaves differently depending on which the role and permissions a logged in user has. To create the users run: + +```sh +node x-pack/plugins/apm/scripts/create-apm-users-and-roles.js --username admin --password changeme --kibana-url http://localhost:5601 --role-suffix +``` + +This will create: + +**apm_read_user**: Read only user + +**apm_power_user**: Read+write user. + +## Debugging Elasticsearch queries + +All APM api endpoints accept `_inspect=true` as a query param that will result in the underlying ES query being outputted in the Kibana backend process. + +Example: +`/api/apm/services/my_service?_inspect=true` +diff --git a/x-pack/plugins/apm/dev_docs/linting.md b/x-pack/plugins/apm/dev_docs/linting.md diff --git a/x-pack/plugins/apm/dev_docs/testing.md b/x-pack/plugins/apm/dev_docs/testing.md new file mode 100644 index 000000000000..93f32111048c --- /dev/null +++ b/x-pack/plugins/apm/dev_docs/testing.md @@ -0,0 +1,66 @@ +# Testing + +## Unit Tests (Jest) + +``` +node scripts/test/jest [--watch] [--updateSnapshot] +``` + +#### Coverage + +HTML coverage report can be found in target/coverage/jest after tests have run. + +``` +open target/coverage/jest/index.html +``` + +--- + +## API Tests + +API tests are separated in two suites: + +- a basic license test suite [default] +- a trial license test suite (the equivalent of gold+) + +``` +node scripts/test/api [--trial] [--help] +``` + +The API tests are located in `x-pack/test/apm_api_integration/`. + +**API Test tips** + +- For debugging access Elasticsearch on http://localhost:9220 (`elastic` / `changeme`) +- To update snapshots append `--updateSnapshots` to the functional_test_runner command + +--- + +## E2E Tests (Cypress) + +``` +node scripts/test/e2e [--trial] [--help] +``` + +The E2E tests are located [here](../../ftr_e2e) + +--- + +## Functional tests (Security and Correlations tests) +TODO: We could try moving this tests to the new e2e tests located at `x-pack/plugins/apm/ftr_e2e`. + +**Start server** + +``` +node scripts/functional_tests_server --config x-pack/test/functional/config.js +``` + +**Run tests** + +``` +node scripts/functional_test_runner --config x-pack/test/functional/config.js --grep='APM specs' +``` + +APM tests are located in `x-pack/test/functional/apps/apm`. +For debugging access Elasticsearch on http://localhost:9220` (elastic/changeme) +diff --git a/x-pack/plugins/apm/scripts/test/README.md b/x-pack/plugins/apm/scripts/test/README.md diff --git a/x-pack/plugins/apm/readme.md b/x-pack/plugins/apm/readme.md index a331bb4e9f11..fe7e77d28986 100644 --- a/x-pack/plugins/apm/readme.md +++ b/x-pack/plugins/apm/readme.md @@ -2,105 +2,28 @@ ## Local environment setup -### Kibana - -``` -git clone git@github.com:elastic/kibana.git -cd kibana/ -yarn kbn bootstrap -yarn start --no-base-path -``` - -### APM Server, Elasticsearch and data - -To access an elasticsearch instance that has live data you have two options: - -#### A. Connect to Elasticsearch on Cloud (internal devs only) - -Find the credentials for the cluster [here](https://github.com/elastic/apm-dev/blob/master/docs/credentials/apm-ui-clusters.md#apmelstcco) - -#### B. Start Elastic Stack and APM data generators - -``` -git clone git@github.com:elastic/apm-integration-testing.git -cd apm-integration-testing/ -./scripts/compose.py start master --all --no-kibana -``` - -_Docker Compose is required_ +[Local setup documentation](./dev_docs/local_setup.md) ## Testing -Go to [tests documentation](./scripts/test/README.md) +[Testing documentation](./dev_docs/testing.md) ## Linting -_Note: Run the following commands from `kibana/`._ - -### Typescript - -``` -node scripts/type_check.js --project x-pack/plugins/apm/tsconfig.json -``` - -### Prettier - -``` -yarn prettier "./x-pack/plugins/apm/**/*.{tsx,ts,js}" --write -``` - -### ESLint - -``` -node scripts/eslint.js x-pack/legacy/plugins/apm -``` - -## Setup default APM users - -APM behaves differently depending on which the role and permissions a logged in user has. To create the users run: - -```sh -node x-pack/plugins/apm/scripts/create-apm-users-and-roles.js --username admin --password changeme --kibana-url http://localhost:5601 --role-suffix -``` - -This will create: - -**apm_read_user**: Read only user - -**apm_power_user**: Read+write user. - -## Debugging Elasticsearch queries - -All APM api endpoints accept `_inspect=true` as a query param that will result in the underlying ES query being outputted in the Kibana backend process. - -Example: -`/api/apm/services/my_service?_inspect=true` +[Linting documentation](./dev_docs/linting.md) ## Storybook -Start the [Storybook](https://storybook.js.org/) development environment with -`yarn storybook apm`. All files with a .stories.tsx extension will be loaded. -You can access the development environment at http://localhost:9001. - -## Experimental features settings - -To set up a flagged feature, add the name of the feature key (`apm:myFeature`) to [commmon/ui_settings_keys.ts](./common/ui_settings_keys.ts) and the feature parameters to [server/ui_settings.ts](./server/ui_settings.ts). - -Test for the feature like: - -```js -import { myFeatureEnabled } from '../ui_settings_keys'; -if (core.uiSettings.get(myFeatureEnabled)) { - doStuff(); -} +**Start** +``` +yarn storybook apm ``` -Settings can be managed in Kibana under Stack Management > Advanced Settings > Observability. +All files with a .stories.tsx extension will be loaded. You can access the development environment at http://localhost:9001. ## Further resources - -- [Cypress integration tests](./e2e/README.md) - [VSCode setup instructions](./dev_docs/vscode_setup.md) - [Github PR commands](./dev_docs/github_commands.md) - [Routing and Linking](./dev_docs/routing_and_linking.md) - [Telemetry](./dev_docs/telemetry.md) +- [Features flags](./dev_docs/feature_flags.md) diff --git a/x-pack/plugins/apm/scripts/test/README.md b/x-pack/plugins/apm/scripts/test/README.md index b241b2efdfd9..2b5e4212ea08 100644 --- a/x-pack/plugins/apm/scripts/test/README.md +++ b/x-pack/plugins/apm/scripts/test/README.md @@ -1,63 +1 @@ -## Unit Tests (Jest) - -``` -node scripts/tests/jest [--watch] [--updateSnapshot] -``` - -#### Coverage - -HTML coverage report can be found in target/coverage/jest after tests have run. - -``` -open target/coverage/jest/index.html -``` - ---- - -## API Tests - -API tests are separated in two suites: - -- a basic license test suite [default] -- a trial license test suite (the equivalent of gold+) - -``` -node scripts/tests/api [--trial] [--help] -``` - -The API tests are located in `x-pack/test/apm_api_integration/`. - -**API Test tips** - -- For debugging access Elasticsearch on http://localhost:9220` (elastic/changeme) -- To update snapshots append `--updateSnapshots` to the functional_test_runner command - ---- - -## E2E Tests (Cypress) - -``` -node scripts/tests/e2e [--trial] [--help] -``` - -The E2E tests are located [here](../../ftr_e2e) - ---- - -## Functional tests (Security and Correlations tests) -TODO: We could try moving this tests to the new e2e tests located at `x-pack/plugins/apm/ftr_e2e`. - -**Start server** - -``` -node scripts/functional_tests_server --config x-pack/test/functional/config.js -``` - -**Run tests** - -``` -node scripts/functional_test_runner --config x-pack/test/functional/config.js --grep='APM specs' -``` - -APM tests are located in `x-pack/test/functional/apps/apm`. -For debugging access Elasticsearch on http://localhost:9220` (elastic/changeme) +Go to [testing documentation](../../dev_docs/testing.md) \ No newline at end of file