diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b67e335b8d2..db00d033819 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -9,7 +9,7 @@ When submitting code, please apply [Square Code Style](https://github.com/square ## License By contributing your code, you agree to license your contribution under -the terms of the [APLv2](LICENSE). +the terms of the [APLv2](../LICENSE). All files are released with the Apache 2.0 license. diff --git a/.github/workflows/create_release.yml b/.github/workflows/create_release.yml index a759f438e74..bd98f762108 100644 --- a/.github/workflows/create_release.yml +++ b/.github/workflows/create_release.yml @@ -1,13 +1,12 @@ -# yamllint --format github .github/workflows/create_release.yml --- name: create_release -# We create a release version on a trigger tag, regardless of if the commit is documentation-only. -# -# See https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet -on: +# We create a release version on a trigger tag, regardless of if the commit is +# documentation-only. +on: # yamllint disable-line rule:truthy push: - tags: 'release-[0-9]+.[0-9]+.[0-9]+**' # Ex. release-1.2.3 + tags: # e.g. release-1.2.3 + - 'release-[0-9]+.[0-9]+.[0-9]+**' jobs: create_release: @@ -16,10 +15,10 @@ jobs: - name: Checkout Repository uses: actions/checkout@v4 with: - # Prevent use of implicit GitHub Actions read-only token GITHUB_TOKEN. We don't deploy on - # the tag MAJOR.MINOR.PATCH event, but we still need to deploy the maven-release-plugin master commit. + # Prevent use of implicit GitHub Actions read-only GITHUB_TOKEN + # because maven-release-plugin pushes commits to master. token: ${{ secrets.GH_TOKEN }} - fetch-depth: 1 # only need the HEAD commit as license check isn't run + fetch-depth: 1 # license check is skipped, so we don't need history - name: Setup java uses: actions/setup-java@v4 with: @@ -36,9 +35,9 @@ jobs: # GH_USER= GH_USER: ${{ secrets.GH_USER }} # GH_TOKEN= - # - makes release commits and tags - # - needs repo:status, public_repo - # - referenced in .settings.xml + # * makes release commits and tags + # * needs repo:status, public_repo + # * referenced in .settings.xml GH_TOKEN: ${{ secrets.GH_TOKEN }} run: | # GITHUB_REF will be refs/tags/release-MAJOR.MINOR.PATCH build-bin/git/login_git && diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index a7e32d663a7..d91daae3c37 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -4,13 +4,14 @@ name: deploy # We deploy on master and release versions, regardless of if the commit is # documentation-only or not. -# -# See https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet -on: +on: # yamllint disable-line rule:truthy push: - # Don't deploy tags as they conflict with [maven-release-plugin] prepare release MAJOR.MINOR.PATCH - tags: '' - branches: master + branches: + - master + # Don't deploy tags because the same commit for MAJOR.MINOR.PATCH is also + # on master: Redundant deployment of a release version will fail uploading. + tags-ignore: + - '*' jobs: deploy: @@ -19,10 +20,11 @@ jobs: - name: Checkout Repository uses: actions/checkout@v4 with: - # Prevent use of implicit GitHub Actions read-only token GITHUB_TOKEN. - # We push Javadocs to the gh-pages branch on commit. + # Prevent use of implicit GitHub Actions read-only GITHUB_TOKEN + # because javadoc_to_gh_pages pushes commits to the gh-pages branch. token: ${{ secrets.GH_TOKEN }} - fetch-depth: 0 # allow build-bin/idl_to_gh_pages to get the full history + # allow build-bin/javadoc_to_gh_pages to get the full history + fetch-depth: 0 - name: Setup java uses: actions/setup-java@v4 with: @@ -38,6 +40,7 @@ jobs: uses: actions/cache@v3 with: path: ~/.npm + # yamllint disable-line rule:line-length key: ${{ runner.os }}-npm-packages-${{ hashFiles('zipkin-lens/package-lock.json') }} # Don't attempt to cache Docker. Sensitive information can be stolen # via forks, and login session ends up in ~/.docker. This is ok because @@ -47,31 +50,30 @@ jobs: # GH_USER= GH_USER: ${{ secrets.GH_USER }} # GH_TOKEN= - # - pushes gh-pages during build-bin/javadoc_to_gh_pages - # - pushes Docker images to ghcr.io - # - create via https://github.com/settings/tokens - # - needs repo:status, public_repo, write:packages, delete:packages + # * pushes gh-pages during build-bin/javadoc_to_gh_pages + # * pushes Docker images to ghcr.io + # * create via https://github.com/settings/tokens + # * needs repo:status, public_repo, write:packages, delete:packages GH_TOKEN: ${{ secrets.GH_TOKEN }} GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }} # GPG_PASSPHRASE= - # - referenced in .settings.xml + # * referenced in .settings.xml GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} # SONATYPE_USER= - # - deploys snapshots and releases to Sonatype - # - needs access to io.zipkin via https://issues.sonatype.org/browse/OSSRH-16669 - # - generate via https://oss.sonatype.org/#profile;User%20Token - # - referenced in .settings.xml + # * deploys snapshots and releases to Sonatype + # * needs access to io.zipkin via OSSRH-16669 + # * generate via https://oss.sonatype.org/#profile;User%20Token + # * referenced in .settings.xml SONATYPE_USER: ${{ secrets.SONATYPE_USER }} # SONATYPE_PASSWORD= - # - referenced in .settings.xml + # * referenced in .settings.xml SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }} # DOCKERHUB_USER= - # - only push top-level projects: zipkin zipkin-aws zipkin-dependencies zipkin-gcp to Docker Hub, only on release - # - login like this: echo "$DOCKERHUB_TOKEN"| docker login -u "$DOCKERHUB_USER" --password-stdin + # * only push repos in openzipkin org to Docker Hub on release DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }} # DOCKERHUB_TOKEN= - # - Access Token from here https://hub.docker.com/settings/security + # * Access Token from here https://hub.docker.com/settings/security DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} - run: | # GITHUB_REF will be refs/heads/master or refs/tags/MAJOR.MINOR.PATCH + run: | # GITHUB_REF = refs/heads/master or refs/tags/MAJOR.MINOR.PATCH build-bin/configure_deploy && build-bin/deploy $(echo ${GITHUB_REF} | cut -d/ -f 3) diff --git a/.github/workflows/docker_push.yml b/.github/workflows/docker_push.yml index 14dd23c902a..30966d5dbd2 100644 --- a/.github/workflows/docker_push.yml +++ b/.github/workflows/docker_push.yml @@ -1,13 +1,12 @@ -# yamllint --format github .github/workflows/docker_push.yml --- name: docker_push -# We re-push docker images on a trigger tag, regardless of if the commit is documentation-only. -# -# See https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet -on: +# We re-push docker on a trigger tag, regardless of if the commit is +# documentation-only. +on: # yamllint disable-line rule:truthy push: - tags: 'docker-[0-9]+.[0-9]+.[0-9]+**' # Ex. docker-1.2.3 + tags: # e.g. release-1.2.3 + - 'release-[0-9]+.[0-9]+.[0-9]+**' jobs: docker_push: @@ -21,7 +20,7 @@ jobs: # via forks, and login session ends up in ~/.docker. This is ok because # we publish DOCKER_PARENT_IMAGE to ghcr.io, hence local to the runner. - name: Docker Push - run: | # GITHUB_REF will be refs/tags/docker-MAJOR.MINOR.PATCH + run: | # GITHUB_REF = refs/tags/docker-MAJOR.MINOR.PATCH build-bin/git/login_git && build-bin/docker/configure_docker_push && build-bin/docker_push $(echo ${GITHUB_REF} | cut -d/ -f 3) @@ -29,14 +28,13 @@ jobs: # GH_USER= GH_USER: ${{ secrets.GH_USER }} # GH_TOKEN= - # - pushes Docker images to ghcr.io - # - create via https://github.com/settings/tokens - # - needs repo:status, public_repo, write:packages, delete:packages + # * pushes Docker images to ghcr.io + # * create via https://github.com/settings/tokens + # * needs repo:status, public_repo, write:packages, delete:packages GH_TOKEN: ${{ secrets.GH_TOKEN }} # DOCKERHUB_USER= - # - only push top-level projects: zipkin zipkin-aws zipkin-dependencies zipkin-gcp to Docker Hub, only on release - # - login like this: echo "$DOCKERHUB_TOKEN"| docker login -u "$DOCKERHUB_USER" --password-stdin + # * only push repos in openzipkin org to Docker Hub on release DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }} # DOCKERHUB_TOKEN= - # - Access Token from here https://hub.docker.com/settings/security + # * Access Token from here https://hub.docker.com/settings/security DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000000..6004746fea6 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,36 @@ +--- +name: lint + +on: # yamllint disable-line rule:truthy + push: # non-tagged pushes to master + branches: + - master + tags-ignore: + - '*' + paths: + - '**/*.md' + - '.github/workflows/*.yml' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + pull_request: # pull requests targeted at the master branch. + branches: + - master + paths: + - '**/*.md' + - '.github/workflows/*.yml' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + +jobs: + lint: + name: Lint + runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + # skip commits made by the release plugin + if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + - name: Lint + run: | + build-bin/configure_lint + build-bin/lint diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 9158ac7b969..7b488a3a242 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,63 +1,43 @@ -# yamllint --format github .github/workflows/test.yml --- name: test # We don't test documentation-only commits. -on: - # We run tests on non-tagged pushes to master that aren't a commit made by the release plugin - push: - tags: "" - branches: master +on: # yamllint disable-line rule:truthy + push: # non-tagged pushes to master + branches: + - master + tags-ignore: + - '*' paths-ignore: - - "**/*.md" - - "charts/**" - # We also run tests on pull requests targeted at the master branch. - pull_request: - branches: master + - '**/*.md' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + pull_request: # pull requests targeted at the master branch. + branches: + - master paths-ignore: - - "**/*.md" - - "charts/**" + - '**/*.md' + - './build-bin/*lint' + - ./build-bin/mlc_config.json jobs: - test-javadoc: - name: Test JavaDoc Builds - runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish - if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" - steps: - - name: Checkout Repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 # full git history for license check - - name: Setup java - uses: actions/setup-java@v4 - with: - distribution: 'zulu' # zulu as it supports a wide version range - java-version: '17' # earliest LTS supported by Spring Boot 3 - - name: Cache local Maven repository - uses: actions/cache@v3 - with: - path: ~/.m2/repository - key: ${{ runner.os }}-jdk-17-maven-${{ hashFiles('**/pom.xml') }} - restore-keys: ${{ runner.os }}-jdk-17-maven- - - name: Build JavaDoc - run: ./mvnw clean javadoc:aggregate -Prelease - test: name: test (JDK ${{ matrix.java_version }}) - runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + # skip commits made by the release plugin if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" strategy: - fail-fast: false # don't fail fast as sometimes failures are operating system specific - matrix: # use latest available versions and be consistent on all workflows! + fail-fast: false # don't fail fast as some failures are LTS specific + matrix: # match with maven-enforcer-plugin rules in pom.xml include: - java_version: 17 # earliest LTS supported by Spring Boot 3 - maven_args: -Prelease -Dgpg.skip -Dmaven.javadoc.skip=true + maven_args: -Prelease -Dgpg.skip - java_version: 21 # Most recent LTS steps: - name: Checkout Repository uses: actions/checkout@v4 with: - fetch-depth: 0 # full git history for license check + fetch-depth: 0 # full git history for license check - name: Setup java uses: actions/setup-java@v4 with: @@ -67,18 +47,23 @@ jobs: uses: actions/cache@v3 with: path: ~/.m2/repository + # yamllint disable-line rule:line-length key: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven- - name: Cache NPM Packages uses: actions/cache@v3 with: path: ~/.npm + # yamllint disable-line rule:line-length key: ${{ runner.os }}-npm-packages-${{ hashFiles('zipkin-lens/package-lock.json') }} - name: Test without Docker - run: build-bin/maven_go_offline && build-bin/test -DexcludedGroups=docker ${{ matrix.maven_args }} + run: | + build-bin/maven_go_offline && + build-bin/test -DexcludedGroups=docker ${{ matrix.maven_args }} test_docker: - runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + # skip commits made by the release plugin if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" strategy: matrix: @@ -94,7 +79,7 @@ jobs: - name: Checkout Repository uses: actions/checkout@v4 with: - fetch-depth: 1 # -Dlicense.skip=true so we don't need a full clone + fetch-depth: 1 # -Dlicense.skip=true, so we don't need a full clone - name: Setup java uses: actions/setup-java@v4 with: @@ -104,6 +89,7 @@ jobs: uses: actions/cache@v3 with: path: ~/.m2/repository + # yamllint disable-line rule:line-length key: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven- # Don't attempt to cache Docker. Sensitive information can be stolen @@ -118,5 +104,8 @@ jobs: run: | build-bin/docker/configure_docker && build-bin/maven/maven_go_offline && - MAVEN_GOAL=install build-bin/maven/maven_build -pl :${{ matrix.name }} --am && - build-bin/test -Dgroups=docker -pl :${{ matrix.name }} -Dlicense.skip=true + build-bin/maven/maven_build -pl :${{ matrix.name }} --am && + build-bin/test -Dgroups=docker -pl :${{ matrix.name }} + env: + MAVEN_GOAL: install # docker build needs dependencies in mavenLocal + MAVEN_CONFIG: '-Dlicense.skip=true' # license check already run diff --git a/.github/workflows/readme_test.yml b/.github/workflows/test_readme.yml similarity index 73% rename from .github/workflows/readme_test.yml rename to .github/workflows/test_readme.yml index eb16dc4479f..a0e0f340858 100644 --- a/.github/workflows/readme_test.yml +++ b/.github/workflows/test_readme.yml @@ -1,30 +1,40 @@ -# yamllint --format github .github/workflows/readme_test.yml --- -name: readme_test +name: test_readme # These test build commands mentioned in various README.md files. # -# This doesn't literally scrape the README.md, so we don't test documentation-only commits. -on: - # We run tests on only on pull requests targeted at the master branch. - # * This skips master pushes as it is rare things not done in PRs break, and conserves resources - pull_request: - branches: master +# We don't test documentation-only commits. +on: # yamllint disable-line rule:truthy + push: # non-tagged pushes to master + branches: + - master + tags-ignore: + - '*' paths-ignore: - - "**/*.md" - - "charts/**" + - '**/*.md' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + pull_request: # pull requests targeted at the master branch. + branches: + - master + paths-ignore: + - '**/*.md' + - './build-bin/*lint' + - ./build-bin/mlc_config.json jobs: zipkin-server: name: zipkin-server/README.md ${{ matrix.name }} runs-on: ${{ matrix.os }} + # skip commits made by the release plugin + if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" strategy: matrix: - include: # ubuntu is tested as a part of the docker job + include: # Not ubuntu as already tested as a part of the docker job - name: macos - os: macos-latest + os: macos-12 - name: windows - os: windows-latest + os: windows-2022 steps: - name: Checkout Repository uses: actions/checkout@v4 @@ -39,6 +49,7 @@ jobs: uses: actions/cache@v3 with: path: ~/.npm + # yamllint disable-line rule:line-length key: ${{ runner.os }}-npm-packages-${{ hashFiles('zipkin-lens/package-lock.json') }} - name: Cache local Maven repository uses: actions/cache@v3 @@ -46,11 +57,15 @@ jobs: path: ~/.m2/repository key: ${{ runner.os }}-jdk-21-maven-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-jdk-21-maven- - - name: Execute Server Build # command from zipkin-server/README.md - run: ./mvnw -T1C -q --batch-mode -DskipTests --also-make -pl zipkin-server clean package + - name: Execute Server Build # command from zipkin-server/README.md + run: ./mvnw --also-make -pl zipkin-server clean package + env: + MAVEN_CONFIG: '-T1C -q --batch-mode -DskipTests' docker: - runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + # skip commits made by the release plugin + if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" steps: - name: Checkout Repository uses: actions/checkout@v4 @@ -60,7 +75,9 @@ jobs: # See https://github.com/actions/virtual-environments/issues/323 - name: Remove broken apt repos run: | - for apt_file in `grep -lr microsoft /etc/apt/sources.list.d/`; do sudo rm $apt_file; done + for apt_file in `grep -lr microsoft /etc/apt/sources.list.d/` + do sudo rm $apt_file + done - name: Setup java uses: actions/setup-java@v4 with: @@ -73,6 +90,7 @@ jobs: uses: actions/cache@v3 with: path: ~/.npm + # yamllint disable-line rule:line-length key: ${{ runner.os }}-npm-packages-${{ hashFiles('zipkin-lens/package-lock.json') }} - name: Cache local Maven repository uses: actions/cache@v3 @@ -80,8 +98,10 @@ jobs: path: ~/.m2/repository key: ${{ runner.os }}-jdk-21-maven-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-jdk-21-maven- - - name: zipkin-server/README.md # Tests the build which is re-used for a few images - run: ./mvnw -T1C -q --batch-mode -DskipTests --also-make -pl zipkin-server clean package + - name: Build zipkin-server # redundant, but needed for docker/README.md + run: ./mvnw --also-make -pl zipkin-server clean package + env: + MAVEN_CONFIG: '-T1C -q --batch-mode -DskipTests' - name: docker/README.md - openzipkin/zipkin run: | build-bin/docker/docker_build openzipkin/zipkin:test && @@ -114,15 +134,17 @@ jobs: DOCKER_FILE: docker/test-images/zipkin-cassandra/Dockerfile - name: docker/test-images/zipkin-elasticsearch7/README.md run: | - build-bin/docker/docker_build openzipkin/zipkin-elasticsearch7:test && - build-bin/docker/docker_test_image openzipkin/zipkin-elasticsearch7:test + build-bin/docker/docker_build ${DOCKER_TAG} && + build-bin/docker/docker_test_image ${DOCKER_TAG} env: + DOCKER_TAG: openzipkin/zipkin-elasticsearch7:test DOCKER_FILE: docker/test-images/zipkin-elasticsearch7/Dockerfile - name: docker/test-images/zipkin-elasticsearch8/README.md run: | - build-bin/docker/docker_build openzipkin/zipkin-elasticsearch8:test && - build-bin/docker/docker_test_image openzipkin/zipkin-elasticsearch8:test + build-bin/docker/docker_build ${DOCKER_TAG} && + build-bin/docker/docker_test_image ${DOCKER_TAG} env: + DOCKER_TAG: openzipkin/zipkin-elasticsearch8:test DOCKER_FILE: docker/test-images/zipkin-elasticsearch8/Dockerfile - name: docker/test-images/zipkin-eureka/README.md run: | diff --git a/README.md b/README.md index e52535276d1..06967e653f0 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,11 @@ You can also start Zipkin via Docker. docker run -d -p 9411:9411 openzipkin/zipkin ``` -Once the server is running, you can view traces with the Zipkin UI at `http://your_host:9411/zipkin/`. +Once the server is running, you can view traces with the Zipkin UI at http://localhost:9411/zipkin. If your applications aren't sending traces, yet, configure them with [Zipkin instrumentation](https://zipkin.io/pages/tracers_instrumentation) or try one of our [examples](https://github.com/openzipkin?utf8=%E2%9C%93&q=example). -Check out the [`zipkin-server`](/zipkin-server) documentation for configuration details, or [Docker examples](docker/examples) for how to use docker-compose. +Check out the [`zipkin-server`](zipkin-server/README.md) documentation for configuration details, or [Docker examples](docker/examples) for how to use docker-compose. ### Zipkin Slim @@ -213,10 +213,10 @@ commits to master. ### Docker Images Released versions of zipkin-server are published to Docker Hub as `openzipkin/zipkin` and GitHub -Container Registry as `ghcr.io/openzipkin/zipkin`. See [docker](./docker) for details. +Container Registry as `ghcr.io/openzipkin/zipkin`. See [docker](docker) for details. ### Helm Charts -Helm charts are available at https://zipkin.io/zipkin-helm. +Helm charts are available via `helm repo add zipkin https://zipkin.io/zipkin-helm`. See [zipkin-helm](https://github.com/openzipkin/zipkin-helm) for details. ### Javadocs diff --git a/build-bin/README.md b/build-bin/README.md index 406daddd7e4..4a4c329dabc 100644 --- a/build-bin/README.md +++ b/build-bin/README.md @@ -38,14 +38,78 @@ CI-provider specific tools, doing so can easily create a dependency where no one release anymore. Do not use provider-specific mechanisms to implement release flow. Instead, automate triggering of the scripts here. -The only scripts that should be modified per project are in the base directory. Those in sub -directories, such as [docker], should not vary project to project except accident of version drift. -Intentional changes in sub directories should be relevant and tested on multiple projects to ensure -they can be blindly copy/pasted. +The only scripts that should be modified per project are in the base directory. Those in +subdirectories, such as [docker](docker), should not vary project to project except accident of +version drift. Intentional changes in subdirectories should be relevant and tested on multiple +projects to ensure they can be blindly copy/pasted. Conversely, the files in the base directory are project specific entry-points for test and deploy actions and are entirely appropriate to vary per project. Here's an overview: +## Lint + +Lint makes sure that documentation and workflows are in-tact. CI providers should be configured to +run lint on pull requests or pushes to the master branch, notably when the tag is blank. Linters +should only run on documentation-only commits or those who affect workflow files. Linters must not +depend on authenticated resources, as running lint can leak credentials. + +* [configure_lint](configure_lint) - Ensures linters are installed +* [lint](lint) - Runs the linters + +We minimally check the following: + +* [markdown-link-check](https://github.com/tcort/markdown-link-check) on our Markdown content. + * we maintain [mlc_config.json](mlc_config.json) for exceptions +* [yamllint](https://github.com/adrienverge/yamllint) on our GitHub Actions Workflow YAML. + * occasionally need line length exceptions via `# yamllint disable-line rule:line-length` + +### Example GitHub Actions setup + +A simplest GitHub Actions `lint.yml` runs linters after configuring them, but only on relevant event +conditions. The name `lint.yml` and job `lint` allows easy references to status badges and parity of +the scripts it uses. + +The `on:` section obviates job creation and resource usage for irrelevant events. Notably, GitHub +Actions includes the ability to skip documentation-only jobs. + +Here's a partial `lint.yml` including only the aspects mentioned above. +```yaml +--- +on: # yamllint disable-line rule:truthy + push: # non-tagged pushes to master + branches: + - master + tags-ignore: + - '*' + paths: + - '**/*.md' + - '.github/workflows/*.yml' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + pull_request: # pull requests targeted at the master branch. + branches: + - master + paths: + - '**/*.md' + - '.github/workflows/*.yml' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + +jobs: + lint: + name: Lint + runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish + # skip commits made by the release plugin + if: "!contains(github.event.head_commit.message, 'maven-release-plugin')" + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + - name: Lint + run: | + build-bin/configure_lint + build-bin/lint +``` + ## Test Test builds and runs any tests of the project, including integration tests. CI providers should be @@ -54,8 +118,8 @@ blank. Tests should not run on documentation-only commits. Tests must not depend resources, as running tests can leak credentials. Git checkouts should include the full history so that license headers or other git analysis can take place. - * [configure_test] - Sets up build environment for tests. - * [test] - Builds and runs tests for this project. + * [configure_test](configure_test) - Sets up build environment for tests. + * [test](test) - Builds and runs tests for this project. ### Example GitHub Actions setup @@ -68,14 +132,23 @@ Actions includes the ability to skip documentation-only jobs. Here's a partial `test.yml` including only the aspects mentioned above. ```yaml -on: - push: - tags: '' - branches: master - paths-ignore: '**/*.md' - pull_request: - branches: master - paths-ignore: '**/*.md' +on: # yamllint disable-line rule:truthy + push: # non-tagged pushes to master + branches: + - master + tags-ignore: + - '*' + paths-ignore: + - '**/*.md' + - './build-bin/*lint' + - ./build-bin/mlc_config.json + pull_request: # pull requests targeted at the master branch. + branches: + - master + paths-ignore: + - '**/*.md' + - './build-bin/*lint' + - ./build-bin/mlc_config.json jobs: test: @@ -97,8 +170,8 @@ providers deploy pushes to master on when the tag is blank, but not on documenta Releases should deploy on version tags (ex `/^[0-9]+\.[0-9]+\.[0-9]+/`), without consideration of if the commit is documentation only or not. - * [configure_deploy] - Sets up environment and logs in, assuming [configure_test] was not called. - * [deploy] - deploys the project, with arg0 being "master" or a release commit like "1.2.3" + * [configure_deploy](configure_deploy) - Sets up environment and logs in. + * [deploy](deploy) - deploys the project, with arg1 being "master" or a release commit like "1.2.3" ### Example GitHub Actions setup @@ -114,24 +187,28 @@ Here's a partial `deploy.yml` including only the aspects mentioned above. Notice explicitly defined and `on.tags` is a [glob pattern](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet). ```yaml -on: +on: # yamllint disable-line rule:truthy push: - tags: '[0-9]+.[0-9]+.[0-9]+**' # e.g. 8.272.10 or 15.0.1_p9 - branches: master + branches: + - master + # Don't deploy tags because the same commit for MAJOR.MINOR.PATCH is also + # on master: Redundant deployment of a release version will fail uploading. + tags-ignore: + - '*' jobs: deploy: + runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish steps: - name: Checkout Repository uses: actions/checkout@v4 with: fetch-depth: 1 # only needed to get the sha label - - name: Configure Deploy - run: build-bin/configure_deploy + - name: Deploy env: GH_USER: ${{ secrets.GH_USER }} GH_TOKEN: ${{ secrets.GH_TOKEN }} - - name: Deploy - # GITHUB_REF will be refs/heads/master or refs/tags/1.2.3 - run: build-bin/deploy $(echo ${GITHUB_REF} | cut -d/ -f 3) + run: | # GITHUB_REF = refs/heads/master or refs/tags/MAJOR.MINOR.PATCH + build-bin/configure_deploy && + build-bin/deploy $(echo ${GITHUB_REF} | cut -d/ -f 3) ``` diff --git a/build-bin/configure_lint b/build-bin/configure_lint new file mode 100755 index 00000000000..3d32fd7013f --- /dev/null +++ b/build-bin/configure_lint @@ -0,0 +1,7 @@ +#!/bin/sh -ue + +# Attempt to install markdown-link-check if absent +markdown-link-check -V || npm install -g markdown-link-check + +# Attempt to install yamllint if absent +yamllint || pip install --user yamllint diff --git a/build-bin/lint b/build-bin/lint new file mode 100755 index 00000000000..f1da6b72a6f --- /dev/null +++ b/build-bin/lint @@ -0,0 +1,4 @@ +#!/bin/sh -ue + +yamllint --format github .github/workflows/*.yml +find . -name \*.md |grep -v node|xargs markdown-link-check -c ./build-bin/mlc_config.json diff --git a/build-bin/mlc_config.json b/build-bin/mlc_config.json new file mode 100644 index 00000000000..7eb0347dc65 --- /dev/null +++ b/build-bin/mlc_config.json @@ -0,0 +1,25 @@ +{ + "ignorePatterns": [ + { + "pattern": "https://oss.sonatype.org/content/repositories/snapshots" + }, + { + "pattern": "http://localhost:9411/api/v[12]/spans" + }, + { + "pattern": "http://localhost:9411/zipkin" + }, + { + "pattern": "http://localhost:9411/zipkin?serviceName=backend" + }, + { + "pattern": "http://localhost:8081" + }, + { + "pattern": "http://localhost:9000/api" + }, + { + "pattern": "http://localhost:3000" + } + ] +} diff --git a/docker/README.md b/docker/README.md index e07bb669969..bb6498e1a64 100644 --- a/docker/README.md +++ b/docker/README.md @@ -41,7 +41,7 @@ We also provide [example compose files](examples/README.md) that integrate colle such as Kafka or Elasticsearch. ## Configuration -Configuration is via environment variables, defined by [zipkin-server](https://github.com/openzipkin/zipkin/blob/master/zipkin-server/README.md). Notably, you'll want to look at the `STORAGE_TYPE` environment variables, which +Configuration is via environment variables, defined by [zipkin-server](../zipkin-server/README.md). Notably, you'll want to look at the `STORAGE_TYPE` environment variables, which include "cassandra", "mysql" and "elasticsearch". Note: the `openzipkin/zipkin-slim` image only supports "elasticsearch" storage. To use other storage types, you must use the main image `openzipkin/zipkin`. @@ -102,7 +102,7 @@ The above is mentioned only for historical reasons. The OpenZipkin community do not support Docker's deprecated container links. ### MySQL -If using an external MySQL server or image, ensure schema and other parameters match the [docs](https://github.com/openzipkin/zipkin/tree/master/zipkin-storage/mysql-v1#applying-the-schema). +If using an external MySQL server or image, ensure schema and other parameters match the [docs](../zipkin-storage/mysql-v1/README.md#applying-the-schema). ## Building images diff --git a/docker/examples/README.md b/docker/examples/README.md index 14f0a5ed2a2..f713e55f06a 100644 --- a/docker/examples/README.md +++ b/docker/examples/README.md @@ -83,7 +83,7 @@ To add Kafka configuration, run: $ docker-compose -f docker-compose-kafka.yml up ``` -Then configure the [Kafka sender](https://github.com/openzipkin/zipkin-reporter-java/blob/master/kafka11/src/main/java/zipkin2/reporter/kafka11/KafkaSender.java) using a `bootstrapServers` value of `host.docker.internal:9092` if your application is inside the same docker network or `localhost:19092` if not, but running on the same host. +Then configure the [Kafka sender](https://github.com/openzipkin/zipkin-reporter-java/blob/master/kafka/src/main/java/zipkin2/reporter/kafka/KafkaSender.java) using a `bootstrapServers` value of `host.docker.internal:9092` if your application is inside the same docker network or `localhost:19092` if not, but running on the same host. In other words, if you are running a sample application on your laptop, you would use `localhost:19092` bootstrap server to send spans to the Kafka broker running in Docker. @@ -141,9 +141,9 @@ $ docker-compose -f docker-compose.yml -f docker-compose-example.yml up ``` Once the services start, open http://localhost:8081/ -* This calls the backend (http://127.0.0.1:9000/api) and shows its result: a formatted date. +* This calls the backend (http://localhost:9000/api) and shows its result: a formatted date. -Afterward, you can view traces that went through the backend via http://127.0.0.1:9411/zipkin?serviceName=backend +Afterward, you can view traces that went through the backend via http://localhost:9411/zipkin?serviceName=backend ## UI diff --git a/zipkin-collector/activemq/RATIONALE.md b/zipkin-collector/activemq/RATIONALE.md index b4c589a6d65..a1c05f41bfb 100644 --- a/zipkin-collector/activemq/RATIONALE.md +++ b/zipkin-collector/activemq/RATIONALE.md @@ -25,7 +25,7 @@ easier in the same way as bundling elasticsearch does. ## On a potential single-transport client -This package is using the normal activemq-jms client. During a [mail thread](http://activemq.2283324.n4.nabble.com/Interest-in-using-ActiveMQ-as-a-trace-data-transport-for-Zipkin-td4749755.html), we learned the +This package is using the normal activemq-jms client. During a [mail thread](https://marc.info/?l=activemq-users&m=155356007513108), we learned the the STOMP and AMQP 1.0 protocol are the more portable options for a portable integration as ActiveMQ, Artemis and RabbitMQ all support these. On the other hand Kafka does not support these protocols. Any future portability work could be limited by this. Meanwhile, using the standard JMS diff --git a/zipkin-lens/README.md b/zipkin-lens/README.md index d671e90caae..4953f72b527 100644 --- a/zipkin-lens/README.md +++ b/zipkin-lens/README.md @@ -37,7 +37,7 @@ It correctly bundles React in production mode and optimizes the build for the be ## Localization We use [LinguiJS](https://lingui.js.org/) for localization of the UI. Translations for strings are -found in the JSON files under [here](./src/translations). The Javascript files in the directory are +found in the JSON files under [here](src/translations). The Javascript files in the directory are compiled from the JSON files. We're always excited to have help maintaining these translations - if you see a string in the UI that is not translated or mistranslated, please feel free to send a PR to the JSON file to fix it. If you can, please run `yarn run compile` to also compile the translation @@ -46,13 +46,13 @@ of it. ### Adding a new locale -To add a new translated locale, first edit [.linguirc](./.linguirc) and add the locale to the +To add a new translated locale, first edit [.linguirc](.linguirc) and add the locale to the `locales` section. Next, run `yarn run extract` to extract a new file under `src/translations` for the locale. Translate as many strings in the JSON file as you can. Then run `yarn run compile` to compile the strings. -Finally, edit [App.jsx](./src/components/App/App.jsx) and -[LanguageSelector.tsx](./src/components/App/LanguageSelector.tsx) to import the new translation and +Finally, edit [App.tsx](src/components/App/App.tsx) and +[LanguageSelector.tsx](src/components/App/LanguageSelector.tsx) to import the new translation and add an entry to the language selector respectively. ## Dev Tools diff --git a/zipkin-server/README.md b/zipkin-server/README.md index 9bb3a149be3..3c18f01fa8b 100644 --- a/zipkin-server/README.md +++ b/zipkin-server/README.md @@ -22,13 +22,13 @@ $ curl -sSL https://zipkin.io/quickstart.sh | bash -s $ java -jar zipkin.jar ``` -Once you've started, browse to http://your_host:9411 to find traces! +Once you've started, browse to http://localhost:9411/zipkin to find traces! ## Endpoints -The following endpoints are defined under the base url http://your_host:9411 -* / - [UI](../zipkin-ui) -* /config.json - [Configuration for the UI](#configuration-for-the-ui) +The following endpoints are defined under the base url `http://your_host:9411` +* / - [UI](../zipkin-lens) +* /config.json - [Configuration for the UI](#ui) * /api/v2 - [API](https://zipkin.io/zipkin-api/#/) * /health - Returns 200 status if OK * /info - Provides the version of the running instance @@ -170,21 +170,21 @@ Zipkin has a web UI, automatically included in the exec jar, and is hosted by de When the UI loads, it reads default configuration from the `/config.json` endpoint. -| Attribute | Property | Description | -|--------------------------|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| environment | zipkin.ui.environment | The value here becomes a label in the top-right corner. Not required. | -| defaultLookback | zipkin.ui.default-lookback | Default duration in millis to look back when finding traces. Affects the "Start time" element in the UI. Defaults to 900000 (15 minutes in millis). | -| searchEnabled | zipkin.ui.search-enabled | If the Discover screen is enabled. Defaults to true. | -| queryLimit | zipkin.ui.query-limit | Default limit for Find Traces. Defaults to 10. | -| instrumented | zipkin.ui.instrumented | Which sites this Zipkin UI covers. Regex syntax. e.g. `http:\/\/example.com\/.*` Defaults to match all websites (`.*`). | -| logsUrl | zipkin.ui.logs-url | Logs query service url pattern. If specified, a button will appear on the trace page and will replace {traceId} in the url by the traceId. Not required. | -| supportUrl | zipkin.ui.support-url | A URL where a user can ask for support. If specified, a link will be placed in the side menu to this URL, for example a page to file support tickets. Not required. | -| archivePostUrl | zipkin.ui.archive-post-url | Url to POST the current trace in Zipkin v2 json format. e.g. 'https://longterm/api/v2/spans'. If specified, a button will appear on the trace page accordingly. Not required. | -| archiveUrl | zipkin.ui.archive-url | Url to a web application serving an archived trace, templated by '{traceId}'. e.g. https://longterm/zipkin/trace/{traceId}'. This is shown in a confirmation message after a trace is successfully POSTed to the `archivePostUrl`. Not required. | -| dependency.enabled | zipkin.ui.dependency.enabled | If the Dependencies screen is enabled. Defaults to true. | -| dependency.lowErrorRate | zipkin.ui.dependency.low-error-rate | The rate of error calls on a dependency link that turns it yellow. Defaults to 0.5 (50%) set to >1 to disable. | -| dependency.highErrorRate | zipkin.ui.dependency.high-error-rate | The rate of error calls on a dependency link that turns it red. Defaults to 0.75 (75%) set to >1 to disable. | -| basePath | zipkin.ui.basepath | path prefix placed into the tag in the UI HTML; useful when running behind a reverse proxy. Default "/zipkin" | +| Attribute | Property | Description | +|--------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| environment | zipkin.ui.environment | The value here becomes a label in the top-right corner. Not required. | +| defaultLookback | zipkin.ui.default-lookback | Default duration in millis to look back when finding traces. Affects the "Start time" element in the UI. Defaults to 900000 (15 minutes in millis). | +| searchEnabled | zipkin.ui.search-enabled | If the Discover screen is enabled. Defaults to true. | +| queryLimit | zipkin.ui.query-limit | Default limit for Find Traces. Defaults to 10. | +| instrumented | zipkin.ui.instrumented | Which sites this Zipkin UI covers. Regex syntax. e.g. `http:\/\/example.com\/.*` Defaults to match all websites (`.*`). | +| logsUrl | zipkin.ui.logs-url | Logs query service url pattern. If specified, a button will appear on the trace page and will replace {traceId} in the url by the traceId. Not required. | +| supportUrl | zipkin.ui.support-url | A URL where a user can ask for support. If specified, a link will be placed in the side menu to this URL, for example a page to file support tickets. Not required. | +| archivePostUrl | zipkin.ui.archive-post-url | Url to POST the current trace in Zipkin v2 json format. e.g. `https://longterm/api/v2/spans`. If specified, a button will appear on the trace page accordingly. Not required. | +| archiveUrl | zipkin.ui.archive-url | Url to a web application serving an archived trace, templated by '{traceId}'. e.g. `https://longterm/zipkin/trace/{traceId}`. This is shown in a confirmation message after a trace is successfully POSTed to the `archivePostUrl`. Not required. | +| dependency.enabled | zipkin.ui.dependency.enabled | If the Dependencies screen is enabled. Defaults to true. | +| dependency.lowErrorRate | zipkin.ui.dependency.low-error-rate | The rate of error calls on a dependency link that turns it yellow. Defaults to 0.5 (50%) set to >1 to disable. | +| dependency.highErrorRate | zipkin.ui.dependency.high-error-rate | The rate of error calls on a dependency link that turns it red. Defaults to 0.75 (75%) set to >1 to disable. | +| basePath | zipkin.ui.basepath | path prefix placed into the tag in the UI HTML; useful when running behind a reverse proxy. Default "/zipkin" | To map properties to environment variables, change them to upper-underscore case format. For example, if using docker you can set `ZIPKIN_UI_QUERY_LIMIT=100` to affect `$.queryLimit` in `/config.json`. @@ -414,7 +414,7 @@ $ ACTIVEMQ_URL=tcp://localhost:61616 java -jar zipkin.jar ### Kafka Collector The Kafka collector is enabled when `KAFKA_BOOTSTRAP_SERVERS` is set to a v0.10+ server. The following settings apply in this case. Some settings -correspond to "New Consumer Configs" in [Kafka documentation](https://kafka.apache.org/documentation/#newconsumerconfigs). +correspond to "New Consumer Configs" in [Kafka documentation](https://kafka.apache.org/documentation/#consumerconfigs). | Variable | New Consumer Config | Description | |---------------------------|---------------------|----------------------------------------------------------------------------------------------| @@ -433,7 +433,7 @@ $ KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:9092 \ #### Other Kafka consumer properties You may need to set other -[Kafka consumer properties](https://kafka.apache.org/documentation/#newconsumerconfigs), in +[Kafka consumer properties](https://kafka.apache.org/documentation/#consumerconfigs), in addition to the ones with explicit properties defined by the collector. In this case, you need to prefix that property name with `zipkin.collector.kafka.overrides` and pass it as a system property argument. @@ -514,7 +514,7 @@ a valid v2 endpoint of the [Eureka REST API](https://github.com/Netflix/eureka/w | Variable | Instance field | Description | |----------------------------|----------------|------------------------------------------------------------------------------------------------| | `DISCOVERY_EUREKA_ENABLED` | N/A | `false` disables Eureka registration. Defaults to `true`. | -| `EUREKA_SERVICE_URL` | N/A | v2 endpoint of Eureka, e.g. https://eureka-prod/eureka/v2. No default | +| `EUREKA_SERVICE_URL` | N/A | v2 endpoint of Eureka, e.g. `https://eureka-prod/eureka/v2`. No default | | `EUREKA_APP_NAME` | .app | The application this instance registers to. Defaults to `zipkin` | | `EUREKA_HOSTNAME` | .hostName | The hostname used with `${QUERY_PORT}` to build the instance `vipAddress`. Defaults to detect. | | `EUREKA_INSTANCE_ID` | .instanceId | Defaults to `${EUREKA_HOSTNAME}:${EUREKA_APP_NAME}:${QUERY_PORT}`. | diff --git a/zipkin-storage/elasticsearch/README.md b/zipkin-storage/elasticsearch/README.md index d555f29c636..dfb9446fa28 100644 --- a/zipkin-storage/elasticsearch/README.md +++ b/zipkin-storage/elasticsearch/README.md @@ -15,10 +15,10 @@ only to healthy addresses. Here are some examples: -* http://1.1.1.1:9200,http://2.2.2.2:19200 -* http://1.1.1.1:9200,http://[2001:db8::c001]:9200 -* http://elasticsearch:9200,http://1.2.3.4:9200 -* http://elasticsearch-1:9200,http://elasticsearch-2:9200 +* `http://1.1.1.1:9200,http://2.2.2.2:19200` +* `http://1.1.1.1:9200,http://[2001:db8::c001]:9200` +* `http://elasticsearch:9200,http://1.2.3.4:9200` +* `http://elasticsearch-1:9200,http://elasticsearch-2:9200` ## Format Spans are stored in version 2 format, which is the same as the [v2 POST endpoint](https://zipkin.io/zipkin-api/#/default/post_spans) @@ -125,7 +125,7 @@ Elasticsearch 7.8 introduces [composable templates](https://www.elastic.co/guide deprecates [legacy/v1 templates](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-templates-v1.html) used in version prior. Merging of multiple templates with matching index patterns is no longer allowed, and Elasticsearch will return error on PUT of the second template with matching index pattern and priority. Templates with matching index patterns are required to have different priorities, and Elasticsearch will -only use the template with the highest priority. This also means that [secondary template](https://gist.github.com/adriancole/1af1259102e7a2da1b3c9103565165d7) +only use the template with the highest priority. This also means that [secondary template](https://gist.github.com/codefromthecrypt/1af1259102e7a2da1b3c9103565165d7) is no longer achievable. By default, Zipkin will use legacy template during initialization, but you can opt to use composable template by diff --git a/zipkin/RATIONALE.md b/zipkin/RATIONALE.md index 36ea97e5ec0..1fc2419a93a 100644 --- a/zipkin/RATIONALE.md +++ b/zipkin/RATIONALE.md @@ -30,7 +30,8 @@ utilities. Zipkin is a library with embedded use cases, such as inside Java agents or Android code. -For example, Android has a [hard limit on total methods in an application](https://developer.android.com/studio/build/multidex#avoid). + +For example, Android has a [hard limit on total methods in an application](https://developer.android.com/build/multidex#avoid). Fields marked private imply accessors in order to share state in the same package. We routinely share state, such as codec internals within a package. If we marked fields private, we'd count against that limit without adding